feat(config): add planner.emergencyPressurePa for MGC rendezvous emergency bypass

Documented, defaults to null (inert). When set, the MGC pre-empts an in-flight
rendezvous lock and re-plans immediately if the resolved header pressure reaches
this canonical-Pa threshold. Mechanism is wired + tested; never fires until a
real value is configured.

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

.gitignore

@@ -0,0 +1,14 @@
+# Repo dev artifacts. Mirrors the deny list in .npmignore so the two stay
+# in sync — anything that shouldn't be committed AND shouldn't ship in the
+# npm tarball goes in both files.
+node_modules/
+
+# Local stub generated by `npm install` in the submodule directory.
+# generalFunctions has no production deps of its own.
+package-lock.json
+
+*.tgz
+.env
+.env.*
+.DS_Store
+npm-debug.log*

.npmignore

@@ -0,0 +1,28 @@
+# === Mirrors .gitignore — items below this block are also excluded from
+#     the npm tarball. Kept here verbatim so npm pack doesn't fall back to
+#     the .gitignore inheritance (silent + surprising). ===
+node_modules/
+package-lock.json
+*.tgz
+.env
+.env.*
+.DS_Store
+npm-debug.log*
+
+# === Dev-only content the npm tarball doesn't need ===
+# Tests + their harness — consumers load index.js, not the test tree.
+test/
+*.test.js
+
+# Wiki / docs — useful in the repo, big in the pack.
+wiki/
+
+# One-off maintenance tooling (wiki generator, etc.) not used at runtime.
+scripts/
+
+# Project memory + IDE configs.
+.claude/
+.codex/
+.repo-mem/
+CLAUDE.md
+CLAUDE.local.md

CONTRACT.md

@@ -0,0 +1,116 @@
+# generalFunctions — Library Contract
+
+> The public API surface that every EVOLV node depends on. Different shape from
+> per-node `CONTRACT.md` files: nodes contract on `msg.topic`, this library
+> contracts on **what `require('generalFunctions')` exports**.
+
+For deep contracts on the post-refactor platform shapes (`BaseDomain`,
+`BaseNodeAdapter`, command registry, `UnitPolicy`, `ChildRouter`,
+`LatestWinsGate`, `HealthStatus`, `statusBadge`), see the platform-level
+[`.claude/refactor/CONTRACTS.md`](../../.claude/refactor/CONTRACTS.md) in the
+EVOLV superproject. This file is the index and stability tag per export.
+
+**Stability tags:**
+- `stable` — API change requires a deprecation cycle and a CONTRACT update here.
+- `experimental` — may change without warning; do not depend on the exact shape in production code paths.
+- `deprecated` — kept for backwards compatibility, slated for removal.
+
+---
+
+## Platform base classes (post-refactor)
+
+| Export | Kind | Stability | Source | Spec |
+|---|---|---|---|---|
+| `BaseDomain` | class | stable | `src/domain/BaseDomain.js` | [.claude/refactor/CONTRACTS.md §3](../../.claude/refactor/CONTRACTS.md) — extend for all specific domain classes |
+| `BaseNodeAdapter` | class | stable | `src/nodered/BaseNodeAdapter.js` | [.claude/refactor/CONTRACTS.md §2](../../.claude/refactor/CONTRACTS.md) — extend for all nodeClass adapters |
+| `CommandRegistry` / `createRegistry` | class / factory | stable | `src/nodered/commandRegistry.js` | [.claude/refactor/CONTRACTS.md §4](../../.claude/refactor/CONTRACTS.md) — builds `Map<topic\|alias, descriptor>` |
+| `ChildRouter` | class | stable | `src/domain/ChildRouter.js` | [.claude/refactor/CONTRACTS.md §5](../../.claude/refactor/CONTRACTS.md) — declarative parent-side child routing |
+| `UnitPolicy` | class | stable | `src/domain/UnitPolicy.js` | [.claude/refactor/CONTRACTS.md §6](../../.claude/refactor/CONTRACTS.md) — canonical-unit declaration + render |
+| `statusBadge` | function | stable | `src/nodered/statusBadge.js` | [.claude/refactor/CONTRACTS.md §7](../../.claude/refactor/CONTRACTS.md) — Node-RED status text/colour |
+| `StatusUpdater` | class | stable | `src/nodered/statusUpdater.js` | Drives `node.status()` every tick |
+| `HealthStatus` | class | stable | `src/domain/HealthStatus.js` | [.claude/refactor/CONTRACTS.md §9](../../.claude/refactor/CONTRACTS.md) — prediction-quality / drift state |
+| `LatestWinsGate` | class | stable | `src/domain/LatestWinsGate.js` | Idempotent-setter gate; prevents redundant dispatches |
+
+## Output formatting
+
+| Export | Kind | Stability | Source | Notes |
+|---|---|---|---|---|
+| `outputUtils` | object | stable | `src/helper/` (re-export) | `.formatMsg(payload, mode)`; `mode ∈ {'process','influxdb'}`; delta compression on `'process'` |
+| `logger` | object | stable | `src/helper/` (re-export) | Structured logger — use instead of `console.log` |
+
+## Measurements
+
+| Export | Kind | Stability | Source | Notes |
+|---|---|---|---|---|
+| `MeasurementContainer` | class | stable | `src/measurements/` | Chainable `.type().variant().position(childId)` store; emits `<type>.<variant>.<position>` on its `emitter` |
+| `POSITIONS`, `POSITION_VALUES`, `isValidPosition` | const + helper | stable | `src/constants/positions.js` | Canonical position labels (`upstream`/`downstream`/`atequipment`/…) |
+
+## Configuration
+
+| Export | Kind | Stability | Source | Notes |
+|---|---|---|---|---|
+| `configManager` | class | stable | `src/configs/` | Loads node-specific JSON schemas from `src/configs/<n>.json`; serves admin endpoint |
+| `configUtils` | object | stable | `src/helper/` | Schema helpers used by `configManager` |
+| `assetApiConfig` | object | stable | `src/configs/assetApiConfig.js` | Asset-registry HTTP backend config |
+| `validation`, `assertions` | object | stable | `src/helper/` | Runtime validation primitives |
+| `MenuManager` | class | stable | `src/menu/` | Dynamic editor dropdown endpoints |
+
+## Child registration
+
+| Export | Kind | Stability | Source | Notes |
+|---|---|---|---|---|
+| `childRegistrationUtils` | object | stable | `src/helper/` | The handshake utilities `BaseNodeAdapter` uses for parent-child wiring |
+
+## Conversion & physics
+
+| Export | Kind | Stability | Source | Notes |
+|---|---|---|---|---|
+| `convert` | object | stable | `src/convert/` | Unit conversions (used by `UnitPolicy`) |
+| `Fysics` | class | stable | `src/convert/fysics.js` | Fluid/hydraulic helpers |
+| `coolprop` | object | stable | `src/coolprop-node/src/index.js` | Thermodynamic property calculations |
+| `gravity` | object | stable | `src/helper/` | Gravity constants and helpers |
+
+## Control & prediction
+
+| Export | Kind | Stability | Source | Notes |
+|---|---|---|---|---|
+| `PIDController` | class | stable | `src/pid/` | Standard PID; positional and velocity forms |
+| `CascadePIDController` | class | stable | `src/pid/` | Cascaded outer/inner PID |
+| `createPidController`, `createCascadePidController` | factory | stable | `src/pid/` | Convenience builders from config |
+| `predict` | object | stable | `src/predict/` | Series prediction / smoothing |
+| `interpolation` | object | stable | `src/predict/` | 1-D and 3-D interpolation primitives |
+| `nrmse` | function | stable | `src/nrmse/` | Normalised RMSE metric (with profile variants) |
+| `stats` | object | stable | `src/stats/` | Mean/variance/quantile helpers |
+| `state` | object | stable | `src/state/` | Generic state-machine helpers |
+
+## Asset registry
+
+| Export | Kind | Stability | Source | Notes |
+|---|---|---|---|---|
+| `assetResolver` | singleton | stable | `src/registry/` | `.resolve(category, modelId)` — sync, case-insensitive, returns `null` on miss |
+| `AssetResolver` | class | stable | `src/registry/` | Resolver type (for testing / alt backends) |
+| `FileBackend`, `HttpBackend` | class | stable | `src/registry/` | Resolver backends |
+| `loadCurve` | function | **deprecated** | `index.js` (shim) | Thin shim over `assetResolver.resolve('curves', ...)`. New code uses the resolver directly. |
+
+---
+
+## Adding a new export
+
+1. Implement the module under `src/<concern>/`.
+2. Re-export it from `index.js` (alphabetical within the concern block).
+3. Add a row to the appropriate table above with the stability tag.
+4. If the export is a new platform shape (a new base class or cross-node protocol),
+   add a section to [.claude/refactor/CONTRACTS.md](../../.claude/refactor/CONTRACTS.md) in the superproject.
+5. Add a test under `test/`.
+
+## Removing an export
+
+1. Mark it **deprecated** in this file (keep the row, change the tag, add a "removed-in" line).
+2. Update every consumer in `nodes/*` to use the replacement.
+3. Bump submodule pin in the superproject for each touched node.
+4. After one release on `development` with no consumers, remove the export and its row.
+
+---
+
+*Source of truth for the export list: `index.js` (barrel). If this file and the
+barrel disagree, the barrel wins — fix this file in the same PR.*

datasets/assetData/assetData.json

@@ -110,6 +110,7 @@
                 { 
                   "id": "hidrostal-pump-001",
                   "name": "hidrostal-H05K-S03R",
+
                   "units": ["l/s"]
                 },
                 { 

datasets/assetData/curves/aerostrip-phoenix.json

@@ -0,0 +1,46 @@
+{
+    "_meta": {
+        "supplier": "Aquaconsult Anlagenbau / Entec",
+        "type": "Strip",
+        "model": "AEROSTRIP",
+        "membrane": "PHOENIX",
+        "membraneArea_m2_per_element": 1.0,
+        "membraneArea_m2_per_element_note": "Aerostrip strips are sized continuously rather than as discrete fixed-area elements. Setting per-element area to 1.0 m² is a normalisation choice: configure the diffuser node with `elements` equal to the total installed strip membrane area in m².",
+        "stdAir": { "temp_C": 0, "pressure_mbar": 1013.25, "RH_pct": 0 },
+        "coverageBasis": "bottom-coverage-pct",
+        "coverageReference": [5, 10, 15, 20],
+        "dataQuality": "multi-coverage",
+        "xAxisBasis": "per-m2-membrane-Nm3h",
+        "yAxisBasis": "ssotr-g-per-Nm3-per-m",
+        "waterDepth_m": 4.75,
+        "sources": [
+            "Floris de Winter (Entec Holland) email to R. de Ren on 2023-11-22 — tabulated SOTE [%] at 4.75 m water depth for bottom coverage 5/10/15/20 % at fluxes 10/25/40/55/70 Nm³/(h*m² membrane). Original chart in 'SSOTE_4.75m different density.pdf'.",
+            "'SSOTR_dP.pdf' — AEROSTRIP fine-bubble diffuser SSOTR + Druckverlust (DWP) chart at water depth 4.05 m, blow-in depth 4.00 m, 21 % bottom coverage. Used for the DWP curve only (read off the vector chart)."
+        ],
+        "note": "SSOTR values are SOTE [%] / water_depth_m × 0.299 kg-O₂/Nm³ × 10 (linear depth scaling). DWP curve was measured at 21 % bottom coverage; pressure loss is intrinsic to the diffuser geometry so the curve is shared across coverage values (single 'p_curve' entry under key '0')."
+    },
+    "sote_curve": {
+        "5":  { "x": [10, 25, 40, 55, 70], "y": [34.20, 28.75, 26.16, 24.89, 24.19] },
+        "10": { "x": [10, 25, 40, 55, 70], "y": [42.01, 35.32, 32.14, 30.58, 29.71] },
+        "15": { "x": [10, 25, 40, 55, 70], "y": [43.39, 36.48, 33.20, 31.59, 30.69] },
+        "20": { "x": [10, 25, 40, 55, 70], "y": [43.80, 36.82, 33.51, 31.88, 30.97] }
+    },
+    "ssote_curve": {
+        "5":  { "x": [10, 25, 40, 55, 70], "y": [7.20, 6.05, 5.51, 5.24, 5.09] },
+        "10": { "x": [10, 25, 40, 55, 70], "y": [8.84, 7.44, 6.77, 6.44, 6.26] },
+        "15": { "x": [10, 25, 40, 55, 70], "y": [9.14, 7.68, 6.99, 6.65, 6.46] },
+        "20": { "x": [10, 25, 40, 55, 70], "y": [9.22, 7.75, 7.06, 6.71, 6.52] }
+    },
+    "otr_curve": {
+        "5":  { "x": [10, 25, 40, 55, 70], "y": [21.53, 18.10, 16.47, 15.67, 15.23] },
+        "10": { "x": [10, 25, 40, 55, 70], "y": [26.44, 22.23, 20.23, 19.25, 18.70] },
+        "15": { "x": [10, 25, 40, 55, 70], "y": [27.31, 22.96, 20.90, 19.89, 19.32] },
+        "20": { "x": [10, 25, 40, 55, 70], "y": [27.57, 23.18, 21.10, 20.06, 19.49] }
+    },
+    "p_curve": {
+        "0": {
+            "x": [5, 10, 25, 40, 55, 70, 80],
+            "y": [46.0, 47.3, 51.1, 54.9, 58.7, 62.4, 65.0]
+        }
+    }
+}

datasets/assetData/curves/gva-elastox-r.json

@@ -0,0 +1,29 @@
+{
+    "_meta": {
+        "supplier": "GVA",
+        "type": "Tube",
+        "model": "ELASTOX-R",
+        "membraneArea_m2_per_element": 0.18,
+        "membraneArea_m2_per_element_source": "placeholder — mirror of Jäger JetFlex TD-65-2-G EPDM 1000 mm (0.18 m²) until a real GVA ELASTOX-R sheet is supplied. Change here when the real value is known; specificClass reads it from this _meta field.",
+        "stdAir": { "temp_C": 0, "pressure_mbar": 1013.25, "RH_pct": 0 },
+        "coverageBasis": "bottom-coverage-pct",
+        "coverageReference": null,
+        "dataQuality": "point",
+        "xAxisBasis": "per-m2-membrane-Nm3h",
+        "yAxisBasis": "ssotr-g-per-Nm3-per-m",
+        "waterDepth_m": null,
+        "note": "Migrated 2026-05-12 from nodes/diffuser/src/specificClass.js _loadSpecs(); the legacy '2.4 elements/m²' tag was a prior mis-conversion of the % bottom-coverage convention. Single-coverage point estimate (key '0' = unspecified). Native data was per-element Nm³/h; converted to per-m²-membrane Nm³/(h·m²) by dividing by the placeholder 0.18 m² element area — those numbers will shift the moment we get a real GVA sheet."
+    },
+    "otr_curve": {
+        "0": {
+            "x": [11.11, 16.67, 22.22, 27.78, 33.33, 38.89, 44.44, 50.00, 55.56],
+            "y": [26, 25, 24, 23.5, 23, 22.75, 22.5, 22.25, 22]
+        }
+    },
+    "p_curve": {
+        "0": {
+            "x": [11.11, 16.67, 22.22, 27.78, 33.33, 38.89, 44.44, 50.00, 55.56, 61.11, 66.67],
+            "y": [40, 42.5, 45, 47.5, 50, 51.5, 53, 54.5, 56, 57.5, 59]
+        }
+    }
+}

datasets/assetData/curves/hidrostal-H05K-S03R.json

@@ -153,7 +153,7 @@
                 100
             ],
             "y": [
-                52.14679487594751,
+                11.142207365162072,
                 20.746724065725342,
                 31.960270693111905,
                 45.6989826531509,
@@ -411,7 +411,7 @@
             "y": [
                 8.219999984177646,
                 13.426327986363882,
-                57.998168647814666,
+                25.971821741448165,
                 42.997354839160536,
                 64.33911122026377
             ]
@@ -427,7 +427,7 @@
             "y": [
                 8.219999984177646,
                 13.426327986363882,
-                53.35067019159144,
+                25.288156424842576,
                 42.48429874246399,
                 64.03769740244357
             ]

datasets/assetData/curves/index.js

@@ -1,129 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-
-class AssetLoader {
-  constructor(maxCacheSize = 100) {
-    this.relPath = './'
-    this.baseDir = path.resolve(__dirname, this.relPath);
-    this.cache = new Map();
-    this.maxCacheSize = maxCacheSize;
-  }
-
-  /**
-   * Load a specific curve by type
-   * @param {string} curveType - The curve identifier (e.g., 'hidrostal-H05K-S03R')
-   * @returns {Object|null} The curve data object or null if not found
-   */
-  loadCurve(curveType) {
-    return this.loadAsset('curves', curveType);
-  }
-
-  /**
-   * Load any asset from a specific dataset folder
-   * @param {string} datasetType - The dataset folder name (e.g., 'curves', 'assetData')
-   * @param {string} assetId - The specific asset identifier
-   * @returns {Object|null} The asset data object or null if not found
-   */
-  loadAsset(datasetType, assetId) {
-    //const cacheKey = `${datasetType}/${assetId}`;
-    const cacheKey = `${assetId}`;
-
-    
-    // Check cache first
-    if (this.cache.has(cacheKey)) {
-      return this.cache.get(cacheKey);
-    }
-
-    try {
-      const filePath = path.join(this.baseDir, `${assetId}.json`);
-
-      // Check if file exists
-      if (!fs.existsSync(filePath)) {
-        console.warn(`Asset not found: ${filePath}`);
-        return null;
-      }
-
-      // Load and parse JSON
-      const rawData = fs.readFileSync(filePath, 'utf8');
-      const assetData = JSON.parse(rawData);
-      
-      // Cache the result (evict oldest if at capacity)
-      if (this.cache.size >= this.maxCacheSize) {
-        const oldestKey = this.cache.keys().next().value;
-        this.cache.delete(oldestKey);
-      }
-      this.cache.set(cacheKey, assetData);
-      
-      return assetData;
-    } catch (error) {
-      console.error(`Error loading asset ${cacheKey}:`, error.message);
-      return null;
-    }
-  }
-
-  /**
-   * Get all available assets in a dataset
-   * @param {string} datasetType - The dataset folder name
-   * @returns {string[]} Array of available asset IDs
-   */
-  getAvailableAssets(datasetType) {
-    try {
-      const datasetPath = path.join(this.baseDir, datasetType);
-      
-      if (!fs.existsSync(datasetPath)) {
-        return [];
-      }
-
-      return fs.readdirSync(datasetPath)
-        .filter(file => file.endsWith('.json'))
-        .map(file => file.replace('.json', ''));
-    } catch (error) {
-      console.error(`Error reading dataset ${datasetType}:`, error.message);
-      return [];
-    }
-  }
-
-  /**
-   * Clear the cache (useful for development/testing)
-   */
-  clearCache() {
-    this.cache.clear();
-  }
-}
-
-// Create and export a singleton instance
-const assetLoader = new AssetLoader();
-
-module.exports = {
-  AssetLoader,
-  assetLoader,
-  // Convenience methods for backward compatibility
-  loadCurve: (curveType) => assetLoader.loadCurve(curveType),
-  loadAsset: (datasetType, assetId) => assetLoader.loadAsset(datasetType, assetId),
-  getAvailableAssets: (datasetType) => assetLoader.getAvailableAssets(datasetType)
-};
-
-/*
-// Example usage in your scripts
-const loader = new AssetLoader();
-
-// Load a specific curve
-const curve = loader.loadCurve('hidrostal-H05K-S03R');
-if (curve) {
-  console.log('Curve loaded:', curve);
-} else {
-  console.log('Curve not found');
-}
-/*
-// Load any asset from any dataset
-const someAsset = loadAsset('assetData', 'some-asset-id');
-
-// Get list of available curves
-const availableCurves = getAvailableAssets('curves');
-console.log('Available curves:', availableCurves);
-
-// Using the class directly for more control
-const { AssetLoader } = require('./index.js');
-const customLoader = new AssetLoader();
-const data = customLoader.loadCurve('hidrostal-H05K-S03R');
-*/

datasets/assetData/curves/jaeger-jetflex-td-65-2-g-epdm-1000.json

@@ -0,0 +1,44 @@
+{
+    "_meta": {
+        "supplier": "Jäger Umwelt-Technik",
+        "type": "Tube",
+        "model": "JetFlex TD 65-2 G",
+        "membrane": "EPDM",
+        "tubeLength_mm": 1000,
+        "totalLength_mm": 1062.5,
+        "outerDiameter_mm": 65,
+        "membraneArea_m2_per_element": 0.18,
+        "operating": {
+            "continuousFlow_Nm3h_per_element": [2, 12],
+            "maxOverloadFlow_Nm3h_per_element": 20,
+            "operatingMode": "continuous-or-intermittent"
+        },
+        "stdAir": { "temp_C": 0, "pressure_mbar": 1013.25, "RH_pct": 0 },
+        "coverageBasis": "bottom-coverage-pct",
+        "coverageReference": null,
+        "dataQuality": "point",
+        "xAxisBasis": "per-m2-membrane-Nm3h",
+        "yAxisBasis": "ssotr-g-per-Nm3-per-m",
+        "waterDepth_m": null,
+        "source": "Jäger Umwelt-Technik 'JETFLEX TD 65-2 G Tube Diffuser' data sheet — vector chart on page 2 ('SSOTE and headloss for EPDM 1000 mm'). Curve coordinates recovered directly from the PDF vector paths on 2026-05-12 (bezier endpoints of the red SSOTE polyline and blue DWP polyline); axis calibration against the gridlines is exact.",
+        "note": "Vendor sheet states neither tank-floor coverage nor water depth at which the SSOTE curve was measured — single-coverage point estimate (key '0' = unspecified), do not extrapolate across density. Native x-axis in the sheet is Nm³/h per tube; converted to canonical Nm³/(h·m² membrane) by dividing by perforated area 0.18 m²."
+    },
+    "ssote_curve": {
+        "0": {
+            "x": [11.11, 16.67, 22.22, 27.78, 33.33, 38.89, 44.44, 50.00, 55.56, 61.11, 66.67],
+            "y": [8.20, 7.85, 7.57, 7.30, 7.10, 6.97, 6.85, 6.72, 6.60, 6.50, 6.40]
+        }
+    },
+    "otr_curve": {
+        "0": {
+            "x": [11.11, 16.67, 22.22, 27.78, 33.33, 38.89, 44.44, 50.00, 55.56, 61.11, 66.67],
+            "y": [24.52, 23.47, 22.63, 21.83, 21.23, 20.84, 20.48, 20.09, 19.73, 19.44, 19.14]
+        }
+    },
+    "p_curve": {
+        "0": {
+            "x": [11.11, 16.67, 22.22, 27.78, 33.33, 38.89, 44.44, 50.00, 55.56, 61.11, 66.67],
+            "y": [25.0, 27.5, 30.0, 32.5, 35.0, 37.5, 40.0, 42.0, 44.0, 46.0, 48.0]
+        }
+    }
+}

datasets/assetData/curves/pik300.json

@@ -0,0 +1,39 @@
+{
+    "_meta": {
+        "supplier": "Sulzer ABS",
+        "type": "Disc",
+        "model": "PIK300",
+        "membrane": "Perforated EPDM",
+        "membraneArea_m2_per_element": 0.07,
+        "membraneArea_m2_per_element_note": "Sulzer ABS PIK/PRK 300 mm fine-bubble disc, ~295 mm active membrane diameter (π × 0.1475² ≈ 0.068 m², rounded to 0.07 m²). Confirm against Sulzer spec sheet if available.",
+        "stdAir": { "temp_C": 0, "pressure_mbar": 1013.25, "RH_pct": 0 },
+        "coverageBasis": "bottom-coverage-pct",
+        "coverageReference": [5, 10, 15, 20, 25],
+        "dataQuality": "multi-coverage",
+        "xAxisBasis": "per-m2-membrane-Nm3h",
+        "yAxisBasis": "ssotr-g-per-Nm3-per-m",
+        "waterDepth_m": 4.0,
+        "source": "'PIK & PRK300 data from QM.xlsx' (Sheet1). Sister model PRK300 shares the SOTE/SSOTR curves; only DWP differs (PIK300 = perforated EPDM, PRK300 = perforated PUR).",
+        "note": "Native data was Sm³/h/disc on X and g O₂/(Sm³·m) on Y (US standard, 20 °C, 1.204 kg/Sm³ → 278.6 g O₂/Sm³). Converted to canonical Nm³ basis (DIN-1343, 0 °C, 1.293 kg/Nm³ → 299.0 g O₂/Nm³): X × 0.9319 / 0.07, Y × 1.0732. Water depth ≈ 4.0 m falls out of the SOTE↔SSOTR ratio under Sm³ conventions — verify if precision matters."
+    },
+    "sote_curve": {
+        "5":  { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [27.87, 26.99, 25.80, 24.97, 24.38, 23.89, 23.46, 23.12] },
+        "10": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [30.18, 29.33, 28.15, 27.33, 26.73, 26.21, 25.83, 25.49] },
+        "15": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [31.51, 30.53, 29.16, 28.27, 27.57, 27.01, 26.55, 26.15] },
+        "20": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [32.52, 31.39, 29.88, 28.84, 28.06, 27.45, 26.92, 26.49] },
+        "25": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [33.26, 32.04, 30.39, 29.27, 28.45, 27.77, 27.22, 26.76] }
+    },
+    "otr_curve": {
+        "5":  { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [20.937, 20.276, 19.382, 18.759, 18.316, 17.947, 17.624, 17.369] },
+        "10": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [22.673, 22.034, 21.148, 20.532, 20.081, 19.690, 19.405, 19.149] },
+        "15": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [23.672, 22.936, 21.907, 21.238, 20.712, 20.291, 19.946, 19.645] },
+        "20": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [24.431, 23.582, 22.447, 21.666, 21.080, 20.622, 20.224, 19.901] },
+        "25": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [24.987, 24.070, 22.831, 21.989, 21.373, 20.862, 20.449, 20.104] }
+    },
+    "p_curve": {
+        "0": {
+            "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49],
+            "y": [25.5,  26.0,  27.5,  30.3,  34.0,  39.0,  45.0,  52.0]
+        }
+    }
+}

datasets/assetData/curves/prk300.json

@@ -0,0 +1,39 @@
+{
+    "_meta": {
+        "supplier": "Sulzer ABS",
+        "type": "Disc",
+        "model": "PRK300",
+        "membrane": "Perforated PUR",
+        "membraneArea_m2_per_element": 0.07,
+        "membraneArea_m2_per_element_note": "Sulzer ABS PIK/PRK 300 mm fine-bubble disc, ~295 mm active membrane diameter (π × 0.1475² ≈ 0.068 m², rounded to 0.07 m²). Confirm against Sulzer spec sheet if available.",
+        "stdAir": { "temp_C": 0, "pressure_mbar": 1013.25, "RH_pct": 0 },
+        "coverageBasis": "bottom-coverage-pct",
+        "coverageReference": [5, 10, 15, 20, 25],
+        "dataQuality": "multi-coverage",
+        "xAxisBasis": "per-m2-membrane-Nm3h",
+        "yAxisBasis": "ssotr-g-per-Nm3-per-m",
+        "waterDepth_m": 4.0,
+        "source": "'PIK & PRK300 data from QM.xlsx' (Sheet1). SOTE/SSOTR curves identical to the sibling PIK300; the only difference is the DWP curve (PRK = perforated PUR vs PIK = perforated EPDM).",
+        "note": "Native data was Sm³/h/disc on X and g O₂/(Sm³·m) on Y. Converted to canonical Nm³ basis (DIN-1343): X × 0.9319 / 0.07, Y × 1.0732."
+    },
+    "sote_curve": {
+        "5":  { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [27.87, 26.99, 25.80, 24.97, 24.38, 23.89, 23.46, 23.12] },
+        "10": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [30.18, 29.33, 28.15, 27.33, 26.73, 26.21, 25.83, 25.49] },
+        "15": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [31.51, 30.53, 29.16, 28.27, 27.57, 27.01, 26.55, 26.15] },
+        "20": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [32.52, 31.39, 29.88, 28.84, 28.06, 27.45, 26.92, 26.49] },
+        "25": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [33.26, 32.04, 30.39, 29.27, 28.45, 27.77, 27.22, 26.76] }
+    },
+    "otr_curve": {
+        "5":  { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [20.937, 20.276, 19.382, 18.759, 18.316, 17.947, 17.624, 17.369] },
+        "10": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [22.673, 22.034, 21.148, 20.532, 20.081, 19.690, 19.405, 19.149] },
+        "15": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [23.672, 22.936, 21.907, 21.238, 20.712, 20.291, 19.946, 19.645] },
+        "20": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [24.431, 23.582, 22.447, 21.666, 21.080, 20.622, 20.224, 19.901] },
+        "25": { "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49], "y": [24.987, 24.070, 22.831, 21.989, 21.373, 20.862, 20.449, 20.104] }
+    },
+    "p_curve": {
+        "0": {
+            "x": [19.97, 26.62, 39.93, 53.24, 66.56, 79.87, 93.18, 106.49],
+            "y": [21.3,  24.0,  29.3,  35.3,  41.3,  46.8,  52.4,  58.6]
+        }
+    }
+}

datasets/assetData/diffuser.json

@@ -0,0 +1,68 @@
+{
+    "id": "diffuser",
+    "label": "diffuser",
+    "softwareType": "diffuser",
+    "suppliers": [
+        {
+            "id": "gva",
+            "name": "GVA",
+            "types": [
+                {
+                    "id": "diffuser-tube",
+                    "name": "Tube",
+                    "models": [
+                        { "id": "gva-elastox-r", "name": "ELASTOX-R", "units": ["Nm3/h"] }
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "jaeger",
+            "name": "Jäger Umwelt-Technik",
+            "types": [
+                {
+                    "id": "diffuser-tube",
+                    "name": "Tube",
+                    "models": [
+                        {
+                            "id": "jaeger-jetflex-td-65-2-g-epdm-1000",
+                            "name": "JetFlex TD 65-2 G — EPDM 1000 mm",
+                            "units": ["Nm3/h"]
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "aquaconsult-entec",
+            "name": "Aquaconsult Anlagenbau (Entec)",
+            "types": [
+                {
+                    "id": "diffuser-strip",
+                    "name": "Strip",
+                    "models": [
+                        {
+                            "id": "aerostrip-phoenix",
+                            "name": "AEROSTRIP — Phoenix membrane",
+                            "units": ["Nm3/h"]
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "id": "sulzer",
+            "name": "Sulzer ABS",
+            "types": [
+                {
+                    "id": "diffuser-disc",
+                    "name": "Disc",
+                    "models": [
+                        { "id": "pik300", "name": "PIK300 — perforated EPDM", "units": ["Nm3/h"] },
+                        { "id": "prk300", "name": "PRK300 — perforated PUR",  "units": ["Nm3/h"] }
+                    ]
+                }
+            ]
+        }
+    ]
+}

datasets/assetData/index.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// AssetCategoryManager is now a thin facade over src/registry/assetResolver.
+// The public surface (getCategory / listCategories / hasCategory / searchCategories)
+// is preserved so existing consumers (src/menu/asset.js, src/helper/assetUtils.js)
+// don't need to change in this phase. New code should use assetResolver directly.
+
+const { assetResolver } = require('../../src/registry');
+
+class AssetCategoryManager {
+    // relPath is retained for signature compatibility with the prior on-disk
+    // implementation; it is unused now — the resolver owns file locations.
+    constructor(/* relPath = '.' */) {}
+
+    getCategory(softwareType) {
+        if (!softwareType) {
+            throw new Error('softwareType is required');
+        }
+        const data = assetResolver.resolve('menu', softwareType);
+        if (!data) {
+            throw new Error(`Asset data '${softwareType}' not found in menu namespace`);
+        }
+        return data;
+    }
+
+    hasCategory(softwareType) {
+        if (!softwareType) return false;
+        return assetResolver.resolve('menu', softwareType) != null;
+    }
+
+    listCategories({ withMeta = false } = {}) {
+        // The resolver indexes each menu file under BOTH its inner softwareType
+        // and its filename slug — those may differ. Dedupe by payload identity
+        // so we return one entry per source file.
+        const seen = new Set();
+        const out = [];
+        for (const key of assetResolver.list('menu')) {
+            const data = assetResolver.resolve('menu', key);
+            if (!data || seen.has(data)) continue;
+            seen.add(data);
+            const softwareType = data.softwareType || key;
+            if (withMeta) {
+                out.push({
+                    softwareType,
+                    label: data.label || softwareType,
+                    file: `${softwareType}.json`,
+                });
+            } else {
+                out.push(softwareType);
+            }
+        }
+        return out;
+    }
+
+    searchCategories(query) {
+        const term = (query || '').trim().toLowerCase();
+        if (!term) return [];
+        return this.listCategories({ withMeta: true }).filter(
+            ({ softwareType, label }) =>
+                softwareType.toLowerCase().includes(term) ||
+                (label || '').toLowerCase().includes(term),
+        );
+    }
+
+    clearCache() {
+        // Caches live in the resolver namespaces. Force-refresh menu.
+        // refresh() is async but the legacy contract here is sync —
+        // fire-and-forget; the next resolve() lazily warms in the worst case.
+        assetResolver.refresh('menu').catch(() => {});
+    }
+}
+
+const assetCategoryManager = new AssetCategoryManager();
+
+module.exports = {
+    AssetCategoryManager,
+    assetCategoryManager,
+    getCategory:      (softwareType) => assetCategoryManager.getCategory(softwareType),
+    listCategories:   (options)      => assetCategoryManager.listCategories(options),
+    searchCategories: (query)        => assetCategoryManager.searchCategories(query),
+    hasCategory:      (softwareType) => assetCategoryManager.hasCategory(softwareType),
+    clearCache:       ()             => assetCategoryManager.clearCache(),
+};

datasets/assetData/measurement.json

@@ -0,0 +1,115 @@
+{
+  "id": "sensor",
+  "label": "Sensor",
+  "softwareType": "measurement",
+  "suppliers": [
+    {
+      "id": "vega",
+      "name": "Vega",
+      "types": [
+        {
+          "id": "temperature",
+          "name": "Temperature",
+          "models": [
+            { "id": "vega-temp-10", "name": "VegaTemp 10", "units": ["degC", "degF"], "product_model_id": 1001, "product_model_uuid": "vega-temp-10" },
+            { "id": "vega-temp-20", "name": "VegaTemp 20", "units": ["degC", "degF"], "product_model_id": 1002, "product_model_uuid": "vega-temp-20" }
+          ]
+        },
+        {
+          "id": "pressure",
+          "name": "Pressure",
+          "models": [
+            { "id": "vega-pressure-10", "name": "VegaPressure 10", "units": ["bar", "mbar", "psi"], "product_model_id": 1003, "product_model_uuid": "vega-pressure-10" },
+            { "id": "vega-pressure-20", "name": "VegaPressure 20", "units": ["bar", "mbar", "psi"], "product_model_id": 1004, "product_model_uuid": "vega-pressure-20" }
+          ]
+        },
+        {
+          "id": "flow",
+          "name": "Flow",
+          "models": [
+            { "id": "vega-flow-10", "name": "VegaFlow 10", "units": ["m3/h", "gpm", "l/min"], "product_model_id": 1005, "product_model_uuid": "vega-flow-10" },
+            { "id": "vega-flow-20", "name": "VegaFlow 20", "units": ["m3/h", "gpm", "l/min"], "product_model_id": 1006, "product_model_uuid": "vega-flow-20" }
+          ]
+        },
+        {
+          "id": "level",
+          "name": "Level",
+          "models": [
+            { "id": "vega-level-10", "name": "VegaLevel 10", "units": ["m", "ft", "mm"], "product_model_id": 1007, "product_model_uuid": "vega-level-10" },
+            { "id": "vega-level-20", "name": "VegaLevel 20", "units": ["m", "ft", "mm"], "product_model_id": 1008, "product_model_uuid": "vega-level-20" }
+          ]
+        },
+        {
+          "id": "oxygen",
+          "name": "Quantity (oxygen)",
+          "models": [
+            { "id": "vega-oxy-10", "name": "VegaOxySense 10", "units": ["g/m3", "mol/m3"], "product_model_id": 1009, "product_model_uuid": "vega-oxy-10" }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "Endress+Hauser",
+      "name": "Endress+Hauser",
+      "types": [
+        {
+          "id": "flow",
+          "name": "Flow",
+          "models": [
+            { "id": "Promag-W400", "name": "Promag W400", "units": ["m3/h", "l/s", "gpm"] },
+            { "id": "Promag-W300", "name": "Promag W300", "units": ["m3/h", "l/s", "gpm"] }
+          ]
+        },
+        {
+          "id": "pressure",
+          "name": "Pressure",
+          "models": [
+            { "id": "Cerabar-PMC51", "name": "Cerabar PMC51", "units": ["mbar", "bar", "psi"] },
+            { "id": "Cerabar-PMC71", "name": "Cerabar PMC71", "units": ["mbar", "bar", "psi"] }
+          ]
+        },
+        {
+          "id": "level",
+          "name": "Level",
+          "models": [
+            { "id": "Levelflex-FMP50", "name": "Levelflex FMP50", "units": ["m", "mm", "ft"] }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "Hach",
+      "name": "Hach",
+      "types": [
+        {
+          "id": "dissolved-oxygen",
+          "name": "Dissolved Oxygen",
+          "models": [
+            { "id": "LDO2", "name": "LDO2", "units": ["mg/L", "ppm"] }
+          ]
+        },
+        {
+          "id": "ammonium",
+          "name": "Ammonium",
+          "models": [
+            { "id": "Amtax-sc", "name": "Amtax sc", "units": ["mg/L"] }
+          ]
+        },
+        {
+          "id": "nitrate",
+          "name": "Nitrate",
+          "models": [
+            { "id": "Nitratax-sc", "name": "Nitratax sc", "units": ["mg/L"] }
+          ]
+        },
+        {
+          "id": "tss",
+          "name": "TSS (Suspended Solids)",
+          "models": [
+            { "id": "Solitax-sc", "name": "Solitax sc", "units": ["mg/L", "g/L"] }
+          ]
+        }
+      ]
+    }
+  ]
+}

datasets/assetData/monsterSamples.json

@@ -0,0 +1,716 @@
+{
+  "samples": [
+    {
+      "code": "106100",
+      "description": "Baarle Nassau influent totaal"
+    },
+    {
+      "code": "106100C",
+      "description": "RWZI Baarle Nassau influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "106120",
+      "description": "Baarle Nassau inhoud beluchtingsruimte"
+    },
+    {
+      "code": "106150",
+      "description": "Baarle Nassau effluent"
+    },
+    {
+      "code": "106209",
+      "description": "Baarle Nassau slibafvoer voorindikker"
+    },
+    {
+      "code": "106400",
+      "description": "Baarle Nassau slibafvoer slibbufferput"
+    },
+    {
+      "code": "109100",
+      "description": "RWZI Chaam influent totaal"
+    },
+    {
+      "code": "109100C",
+      "description": "RWZI Chaam influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "109120",
+      "description": "RWZI Chaam inhoud beluchtingstank"
+    },
+    {
+      "code": "109150",
+      "description": "RWZI Chaam effluent"
+    },
+    {
+      "code": "109153",
+      "description": "RWZI Chaam afloop cascade"
+    },
+    {
+      "code": "109400",
+      "description": "Chaam slib afvoer slibbufferput"
+    },
+    {
+      "code": "112004",
+      "description": "RWZI Dongemond diverse onderzoeken"
+    },
+    {
+      "code": "112062",
+      "description": "RWZI Dongemond RUWE(geleverde) PE zeefbandpers"
+    },
+    {
+      "code": "112100",
+      "description": "RWZI Dongemond influent totaal"
+    },
+    {
+      "code": "112100C",
+      "description": "RWZI Dongemond influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "112110",
+      "description": "RWZI Dongemond afloop voorbezinktank"
+    },
+    {
+      "code": "112121",
+      "description": "RWZI Dongemond inhoud beluchtingstank 1"
+    },
+    {
+      "code": "112122",
+      "description": "RWZI Dongemond inhoud beluchtingstank 2"
+    },
+    {
+      "code": "112123",
+      "description": "RWZI Dongemond inhoud beluchtingstank 3"
+    },
+    {
+      "code": "112124",
+      "description": "RWZI Dongemond inhoud beluchtingstank 4"
+    },
+    {
+      "code": "112150",
+      "description": "RWZI Dongemond effluent"
+    },
+    {
+      "code": "112203",
+      "description": "RWZI Dongemond inhoud container zandvanger"
+    },
+    {
+      "code": "112206",
+      "description": "RWZI Dongemond ingedikt primair slib"
+    },
+    {
+      "code": "112211",
+      "description": "RWZI Dongemond ingedikt secundair slib"
+    },
+    {
+      "code": "112231",
+      "description": "RWZI Dongemond afvoer bandindikker"
+    },
+    {
+      "code": "112244",
+      "description": "RWZI Dongemond inhoud gistingstank"
+    },
+    {
+      "code": "112287",
+      "description": "RWZI Dongemond waterafvoer zeefbandpers totaal"
+    },
+    {
+      "code": "112425",
+      "description": "RWZI Dongemond afvoer slibkoek silo"
+    },
+    {
+      "code": "112569",
+      "description": "RWZI Dongemond Al2(SO4)3"
+    },
+    {
+      "code": "115100",
+      "description": "RWZI Kaatsheuvel influent totaal"
+    },
+    {
+      "code": "115100C",
+      "description": "RWZI Kaatsheuvel influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "115120",
+      "description": "RWZI Kaatsheuvel inhoud beluchtingsruimte"
+    },
+    {
+      "code": "115150",
+      "description": "RWZI Kaatsheuvel effluent"
+    },
+    {
+      "code": "115155",
+      "description": "RWZI Kaatsheuvel toevoer zandfilter"
+    },
+    {
+      "code": "115156",
+      "description": "RWZI Kaatsheuvel afvoer zandfilter"
+    },
+    {
+      "code": "115157",
+      "description": "RWZI Kaatsheuvel afvoer waswater zandfilter"
+    },
+    {
+      "code": "115166",
+      "description": "RWZI Kaatsheuvel Voor UV filter"
+    },
+    {
+      "code": "115167",
+      "description": "RWZI Kaatsheuvel Na UV filter"
+    },
+    {
+      "code": "115203",
+      "description": "RWZI Kaatsheuvel inhoud container zandvanger"
+    },
+    {
+      "code": "115209",
+      "description": "RWZI Kaatsheuvel slibafvoer voorindikker"
+    },
+    {
+      "code": "115400",
+      "description": "RWZI Kaatsheuvel slibafvoer slibbufferput"
+    },
+    {
+      "code": "116100",
+      "description": "RWZI Lage-Zwaluwe influent totaal"
+    },
+    {
+      "code": "116100C",
+      "description": "RWZI Lage-Zwaluwe influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "116120",
+      "description": "RWZI Lage-Zwaluwe inhoud beluchtingsruimte"
+    },
+    {
+      "code": "116150",
+      "description": "RWZI Lage-Zwaluwe effluent"
+    },
+    {
+      "code": "116400",
+      "description": "RWZI Lage-Zwaluwe slibafvoer slibbufferput"
+    },
+    {
+      "code": "121100",
+      "description": "RWZI Riel influent totaal"
+    },
+    {
+      "code": "121100C",
+      "description": "RWZI Riel influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "121120",
+      "description": "RWZI Riel inhoud beluchtingruimte"
+    },
+    {
+      "code": "121150",
+      "description": "RWZI Riel effluent"
+    },
+    {
+      "code": "121203",
+      "description": "RWZI Riel inhoud container zandvanger"
+    },
+    {
+      "code": "121400",
+      "description": "RWZI Riel slibafvoer slibbufferput"
+    },
+    {
+      "code": "124089",
+      "description": "RWZI Rijen aanvoer kolkenzuigermateriaal"
+    },
+    {
+      "code": "124100",
+      "description": "RWZI Rijen influent totaal"
+    },
+    {
+      "code": "124100C",
+      "description": "RWZI Rijen influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "124110",
+      "description": "RWZI Rijen afloop voorbezinktank"
+    },
+    {
+      "code": "124120",
+      "description": "RWZI Rijen inhoud beluchtingsruimte"
+    },
+    {
+      "code": "124150",
+      "description": "RWZI Rijen effluent"
+    },
+    {
+      "code": "124151",
+      "description": "RWZI Rijen effluent voor legionella"
+    },
+    {
+      "code": "124203",
+      "description": "RWZI Rijen inhoud container zandvanger"
+    },
+    {
+      "code": "124206",
+      "description": "RWZI Rijen ingedikt primair slib"
+    },
+    {
+      "code": "124211",
+      "description": "RWZI Rijen ingedikt secundair slib"
+    },
+    {
+      "code": "124350",
+      "description": "RWZI Rijen Toevoer bandindikker"
+    },
+    {
+      "code": "124351",
+      "description": "RWZI Rijen Afvoer bandindikker"
+    },
+    {
+      "code": "124352",
+      "description": "RWZI Rijen waterafvoer bandindikker"
+    },
+    {
+      "code": "124400",
+      "description": "RWZI Rijen slibafvoer"
+    },
+    {
+      "code": "124540",
+      "description": "RWZI Rijen RUWE(geleverde) PE bandindikker"
+    },
+    {
+      "code": "127100",
+      "description": "RWZI Waalwijk influent totaal"
+    },
+    {
+      "code": "127100C",
+      "description": "RWZI Waalwijk influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "127110",
+      "description": "RWZI Waalwijk afloop VBT"
+    },
+    {
+      "code": "127121",
+      "description": "RWZI Waalwijk inhoud beluchtingsruimte 1"
+    },
+    {
+      "code": "127122",
+      "description": "RWZI Waalwijk inhoud beluchtingsruimte 2"
+    },
+    {
+      "code": "127150",
+      "description": "RWZI Waalwijk effluent"
+    },
+    {
+      "code": "127203",
+      "description": "RWZI Waalwijk inhoud container zandvanger"
+    },
+    {
+      "code": "127206",
+      "description": "RWZI Waalwijk ingedikt primair slib"
+    },
+    {
+      "code": "127211",
+      "description": "RWZI Waalwijk ingedikt secundair slib"
+    },
+    {
+      "code": "127244",
+      "description": "RWZI Waalwijk inhoud gistingstank"
+    },
+    {
+      "code": "127450",
+      "description": "RWZI Waalwijk slibafvoer indiklagune"
+    },
+    {
+      "code": "131100",
+      "description": "RWZI Waspik industrie & dorp influent totaal"
+    },
+    {
+      "code": "131100C",
+      "description": "RWZI Waspik influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "131120",
+      "description": "RWZI Waspik inhoud beluchtingsruimte"
+    },
+    {
+      "code": "131150",
+      "description": "RWZI Waspik effluent"
+    },
+    {
+      "code": "131400",
+      "description": "RWZI Waspik slibafvoer slibbufferput"
+    },
+    {
+      "code": "131581",
+      "description": "Waspik Levering Aluminiumchloride 9%"
+    },
+    {
+      "code": "142062",
+      "description": "RWZI Nieuwveer RUWE(geleverde) PE zeefbandpers"
+    },
+    {
+      "code": "142078",
+      "description": "RWZI Nieuwveer Cloetta suikerwater"
+    },
+    {
+      "code": "142089",
+      "description": "RWZI Nieuwveer aanvoer kolkenzuigermateriaal"
+    },
+    {
+      "code": "142105",
+      "description": "RWZI Nieuwveer afloop influentvijzels"
+    },
+    {
+      "code": "142105C",
+      "description": "RWZI Nieuwveer afloop influentvijzels - Monstername influent COVID-19"
+    },
+    {
+      "code": "142110",
+      "description": "RWZI Nieuwveer afloop TBT"
+    },
+    {
+      "code": "142121",
+      "description": "RWZI Nieuwveer inhoud beluchtingsruimte 1"
+    },
+    {
+      "code": "142122",
+      "description": "RWZI Nieuwveer inhoud beluchtingsruimte 2"
+    },
+    {
+      "code": "142123",
+      "description": "RWZI Nieuwveer inhoud beluchtingsruimte 3"
+    },
+    {
+      "code": "142124",
+      "description": "RWZI Nieuwveer inhoud beluchtingsruimte 4"
+    },
+    {
+      "code": "142150",
+      "description": "RWZI Nieuwveer effluent"
+    },
+    {
+      "code": "142174",
+      "description": "RWZI Nieuwveer secundair spuislib"
+    },
+    {
+      "code": "142203",
+      "description": "RWZI Nieuwveer inhoud container zandvanger"
+    },
+    {
+      "code": "142301",
+      "description": "RWZI Nieuwveer slibafvoer Bandindikker 1"
+    },
+    {
+      "code": "142302",
+      "description": "RWZI Nieuwveer slibafvoer Bandindikker 2"
+    },
+    {
+      "code": "142303",
+      "description": "RWZI Nieuwveer slibafvoer Bandindikker 3"
+    },
+    {
+      "code": "142310",
+      "description": "RWZI Nieuwveer monitor slibafvoer ESOMT"
+    },
+    {
+      "code": "142311",
+      "description": "RWZI Nieuwveer afloop Gisting"
+    },
+    {
+      "code": "142325",
+      "description": "RWZI Nieuwveer Influent DEMON"
+    },
+    {
+      "code": "142326",
+      "description": "RWZI Nieuwveer Inhoud DEMON"
+    },
+    {
+      "code": "142327",
+      "description": "RWZI Nieuwveer Effluent DEMON"
+    },
+    {
+      "code": "142332",
+      "description": "RWZI Nieuwveer retourwater slibverwerking"
+    },
+    {
+      "code": "142425",
+      "description": "RWZI Nieuwveer afvoer slibkoek silo"
+    },
+    {
+      "code": "142571",
+      "description": "RWZI Nieuwveer ijzersulfaat levering totaal"
+    },
+    {
+      "code": "144007",
+      "description": "Bouvigne Toevoer helofytenfilter"
+    },
+    {
+      "code": "144008",
+      "description": "Bouvigne Afvoer helofytenfilter"
+    },
+    {
+      "code": "144061",
+      "description": "144061 (toevoer verticale helofytenfilters)"
+    },
+    {
+      "code": "144062",
+      "description": "144062 (afvoer verticale helofytenfilters)"
+    },
+    {
+      "code": "144063",
+      "description": "144063 (afvoer horizontale helofytenfilters)"
+    },
+    {
+      "code": "144064",
+      "description": "144064 (kwaliteit voorberging)"
+    },
+    {
+      "code": "160061",
+      "description": "RWZI Bath RUWE(geleverde) PE bandindikker"
+    },
+    {
+      "code": "160062",
+      "description": "RWZI Bath RUWE(geleverde) PE zeefbandpers"
+    },
+    {
+      "code": "160100",
+      "description": "Bath influent totaal"
+    },
+    {
+      "code": "160100C",
+      "description": "RWZI Bath influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "160110",
+      "description": "Bath Afloop Voorbezinktank West (1 en 3)"
+    },
+    {
+      "code": "160112",
+      "description": "Bath Afloop Voorbezinktank Oost (2 en 4)"
+    },
+    {
+      "code": "160121",
+      "description": "Bath inhoud beluchtingsruimte 1, sectie 4"
+    },
+    {
+      "code": "160122",
+      "description": "Bath inhoud beluchtingsruimte 2, sectie 4"
+    },
+    {
+      "code": "160123",
+      "description": "Bath inhoud beluchtingsruimte 3, sectie 4"
+    },
+    {
+      "code": "160124",
+      "description": "Bath inhoud beluchtingsruimte 4, sectie 4"
+    },
+    {
+      "code": "160125",
+      "description": "Bath inhoud beluchtingsruimte 5, sectie 4"
+    },
+    {
+      "code": "160126",
+      "description": "Bath inhoud beluchtingsruimte 6, sectie 4"
+    },
+    {
+      "code": "160127",
+      "description": "Bath inhoud beluchtingsruimte 7, sectie 4"
+    },
+    {
+      "code": "160128",
+      "description": "Bath inhoud beluchtingsruimte 8, sectie 4"
+    },
+    {
+      "code": "160129",
+      "description": "Bath inhoud beluchtingsruimte 9, sectie 4"
+    },
+    {
+      "code": "160130",
+      "description": "Bath inhoud beluchtingsruimte 10, sectie 4"
+    },
+    {
+      "code": "160150",
+      "description": "Bath effluent"
+    },
+    {
+      "code": "160206",
+      "description": "Bath ingedikt primair slib"
+    },
+    {
+      "code": "160245",
+      "description": "Bath inhoud gistingstank 1 ZB"
+    },
+    {
+      "code": "160246",
+      "description": "Bath inhoud gistingstank 2 ZB"
+    },
+    {
+      "code": "160415",
+      "description": "Bath 160415 Ingedikt Sec.slib BI 1-4 (Buffer)"
+    },
+    {
+      "code": "160425",
+      "description": "Bath afvoer slibkoek silo"
+    },
+    {
+      "code": "169100",
+      "description": "RWZI Dinteloord influent totaal"
+    },
+    {
+      "code": "169100C",
+      "description": "RWZI Dinteloord influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "169120",
+      "description": "RWZI Dinteloord inhoud beluchtingsruimte"
+    },
+    {
+      "code": "169150",
+      "description": "RWZI Dinteloord effluent"
+    },
+    {
+      "code": "169209",
+      "description": "RWZI Dinteloord slibafvoer voorindikker"
+    },
+    {
+      "code": "169400",
+      "description": "RWZI Dinteloord slibafvoer slibbufferput"
+    },
+    {
+      "code": "169700",
+      "description": "RWZI Dinteloord Peilbuis ref 01"
+    },
+    {
+      "code": "169705",
+      "description": "RWZI Dinteloord Peilbuis ref 02"
+    },
+    {
+      "code": "169710",
+      "description": "RWZI Dinteloord Peilbuis 03"
+    },
+    {
+      "code": "169715",
+      "description": "RWZI Dinteloord Peilbuis 04"
+    },
+    {
+      "code": "169720",
+      "description": "RWZI Dinteloord Peilbuis 05"
+    },
+    {
+      "code": "172100",
+      "description": "RWZI Halsteren influent"
+    },
+    {
+      "code": "172100C",
+      "description": "RWZI Halsteren influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "172120",
+      "description": "RWZI Halsteren inhoud beluchtingsruimte"
+    },
+    {
+      "code": "172150",
+      "description": "RWZI Halsteren effluent"
+    },
+    {
+      "code": "172209",
+      "description": "RWZI Halsteren slibafvoer voorindikker"
+    },
+    {
+      "code": "172400",
+      "description": "RWZI Halsteren slibafvoer slibbufferput"
+    },
+    {
+      "code": "181100",
+      "description": "RWZI Nieuw-Vossemeer influent totaal"
+    },
+    {
+      "code": "181100C",
+      "description": "RWZI Nieuw-Vossemeer influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "181120",
+      "description": "RWZI Nieuw-Vossemeer inhoud beluchtingsruimte"
+    },
+    {
+      "code": "181150",
+      "description": "RWZI Nieuw-Vossemeer Effluent steekmonster"
+    },
+    {
+      "code": "181156",
+      "description": "RWZI Nieuw-Vossemeer Effluent waterharmonica steekmonster"
+    },
+    {
+      "code": "181400",
+      "description": "Nieuw Vossemeer slibafvoer slibbufferput"
+    },
+    {
+      "code": "184100",
+      "description": "RWZI Ossendrecht influent totaal"
+    },
+    {
+      "code": "184100C",
+      "description": "RWZI Ossendrecht influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "184120",
+      "description": "RWZI Ossendrecht inhoud beluchtingsruimte"
+    },
+    {
+      "code": "184150",
+      "description": "RWZI Ossendrecht effluent"
+    },
+    {
+      "code": "184460",
+      "description": "RWZI Ossendrecht afvoer slibpersleiding naar AWP"
+    },
+    {
+      "code": "191100",
+      "description": "RWZI Putte influent totaal"
+    },
+    {
+      "code": "191100C",
+      "description": "RWZI Putte influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "191120",
+      "description": "RWZI Putte inhoud beluchtingsruimte"
+    },
+    {
+      "code": "191150",
+      "description": "RWZI Putte effluent"
+    },
+    {
+      "code": "191460",
+      "description": "RWZI Putte afvoer slibpersleiding naar AWP"
+    },
+    {
+      "code": "196100",
+      "description": "RWZI Willemstad influent totaal"
+    },
+    {
+      "code": "196100C",
+      "description": "RWZI Willemstad influent - Monstername influent COVID-19"
+    },
+    {
+      "code": "196120",
+      "description": "RWZI Willemstad inhoud beluchtingsruimte"
+    },
+    {
+      "code": "196150",
+      "description": "RWZI Willemstad effluent"
+    },
+    {
+      "code": "196400",
+      "description": "RWZI Willemstad slibafvoer slibbufferput"
+    },
+    {
+      "code": "303203",
+      "description": "Persstation Bergen op Zoom inh. container zandvang"
+    },
+    {
+      "code": "312203",
+      "description": "AWP persstation Roosendaal inh. container zandvang"
+    },
+    {
+      "code": "WSBD Toeslag Weekendbemonsteri",
+      "description": "WSBD Toeslag Weekendbemonsteringen"
+    }
+  ]
+}

datasets/assetData/rotatingmachine.json

@@ -0,0 +1,34 @@
+{
+  "id": "rotatingmachine",
+  "label": "rotatingMachine",
+  "softwareType": "rotatingmachine",
+  "suppliers": [
+    {
+      "id": "hidrostal",
+      "name": "Hidrostal",
+      "types": [
+        {
+          "id": "pump-centrifugal",
+          "name": "Centrifugal",
+          "models": [
+            {
+              "id": "hidrostal-H05K-S03R",
+              "name": "hidrostal-H05K-S03R",
+              "units": [
+                "l/s",
+                "m3/h"
+              ]
+            },
+            {
+              "id": "hidrostal-C5-D03R-SHN1",
+              "name": "hidrostal-C5-D03R-SHN1",
+              "units": [
+                "l/s"
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

datasets/assetData/valve.json

@@ -0,0 +1,27 @@
+{
+  "id": "valve",
+  "label": "valve",
+  "softwareType": "valve",
+  "suppliers": [
+    {
+      "id": "binder",
+      "name": "Binder Engineering",
+      "types": [
+        {
+          "id": "valve-gate",
+          "name": "Gate",
+          "models": [
+            { "id": "binder-valve-001", "name": "ECDV", "units": ["m3/h", "gpm", "l/min"] }
+          ]
+        },
+        {
+          "id": "valve-jet",
+          "name": "Jet",
+          "models": [
+            { "id": "binder-valve-002", "name": "JCV", "units": ["m3/h", "gpm", "l/min"] }
+          ]
+        }
+      ]
+    }
+  ]
+}

index.js

@@ -8,38 +8,61 @@
  */
 
 // Core helper modules
-const outputUtils = require('./src/helper/outputUtils.js');
-const logger = require('./src/helper/logger.js');
-const validation = require('./src/helper/validationUtils.js');
-const configUtils = require('./src/helper/configUtils.js');
-const assertions = require('./src/helper/assertionUtils.js')
+const helper = require('./src/helper/index.js');
+const {
+    outputUtils,
+    logger,
+    validation,
+    configUtils,
+    assertions,
+    childRegistrationUtils,
+    gravity,
+} = helper;
 const coolprop = require('./src/coolprop-node/src/index.js');
+const assetApiConfig = require('./src/configs/assetApiConfig.js');
 
 // Domain-specific modules
 const { MeasurementContainer } = require('./src/measurements/index.js');
 const configManager = require('./src/configs/index.js');
-const nrmse = require('./src/nrmse/errorMetrics.js');
-const state = require('./src/state/state.js');
+const { nrmse } = require('./src/nrmse/index.js');
+const { state } = require('./src/state/index.js');
 const convert = require('./src/convert/index.js');
 const MenuManager = require('./src/menu/index.js');
-const predict = require('./src/predict/predict_class.js');
-const interpolation = require('./src/predict/interpolation.js');
-const childRegistrationUtils = require('./src/helper/childRegistrationUtils.js');
-const { loadCurve } = require('./datasets/assetData/curves/index.js');
+const { predict, interpolation } = require('./src/predict/index.js');
+const { PIDController, CascadePIDController, createPidController, createCascadePidController } = require('./src/pid/index.js');
+const { AssetResolver, FileBackend, HttpBackend, assetResolver } = require('./src/registry/index.js');
+
+// loadCurve(model) is now a thin shim over assetResolver.resolve('curves', model).
+// Same contract: sync, case-insensitive, returns null on miss. New code should
+// prefer `assetResolver.resolve('curves', ...)` directly; this shim is kept so
+// external consumers don't have to change in one go.
+function loadCurve(modelId) {
+    return assetResolver.resolve('curves', modelId);
+}
 const { POSITIONS, POSITION_VALUES, isValidPosition } = require('./src/constants/positions.js');
 const Fysics = require('./src/convert/fysics.js');
 
-// Gravity helper (used by rotatingMachine for efficiency calculations)
-const gravity = {
-    getStandardGravity: () => 9.80665,
-    fysics: new Fysics()
-};
+// Refactor platform infrastructure (additive — see .claude/refactor/CONTRACTS.md).
+// Domain-side
+const UnitPolicy = require('./src/domain/UnitPolicy.js');
+const ChildRouter = require('./src/domain/ChildRouter.js');
+const LatestWinsGate = require('./src/domain/LatestWinsGate.js');
+const HealthStatus = require('./src/domain/HealthStatus.js');
+const BaseDomain = require('./src/domain/BaseDomain.js');
+// Node-RED-side
+const { statusBadge } = require('./src/nodered/statusBadge.js');
+const { StatusUpdater } = require('./src/nodered/statusUpdater.js');
+const { createRegistry, CommandRegistry } = require('./src/nodered/commandRegistry.js');
+const BaseNodeAdapter = require('./src/nodered/BaseNodeAdapter.js');
+// Stats helpers
+const stats = require('./src/stats/index.js');
 
 // Export everything
 module.exports = {
     predict,
     interpolation,
     configManager,
+    assetApiConfig,
     outputUtils,
     configUtils,
     logger,
@@ -51,10 +74,34 @@ module.exports = {
     coolprop,
     convert,
     MenuManager,
+    PIDController,
+    CascadePIDController,
+    createPidController,
+    createCascadePidController,
     childRegistrationUtils,
     loadCurve,
     gravity,
     POSITIONS,
     POSITION_VALUES,
-    isValidPosition
+    isValidPosition,
+    Fysics,
+    // refactor infra (Phase 1)
+    UnitPolicy,
+    ChildRouter,
+    LatestWinsGate,
+    HealthStatus,
+    BaseDomain,
+    statusBadge,
+    StatusUpdater,
+    createRegistry,
+    CommandRegistry,
+    BaseNodeAdapter,
+    stats,
+    // Asset metadata registry (replaces loadCurve / AssetCategoryManager /
+    // ad-hoc JSON readers — see src/registry/README.md). Backend-swappable;
+    // sync at runtime by contract.
+    AssetResolver,
+    FileBackend,
+    HttpBackend,
+    assetResolver,
 };

package.json

@@ -9,11 +9,17 @@
     "./menuUtils":   "./src/helper/menuUtils.js",
     "./mathUtils":   "./src/helper/mathUtils.js",
     "./assetUtils":  "./src/helper/assetUtils.js",
-    "./outputUtils": "./src/helper/outputUtils.js"
+    "./outputUtils": "./src/helper/outputUtils.js",
+    "./helper": "./src/helper/index.js",
+    "./state": "./src/state/index.js",
+    "./predict": "./src/predict/index.js",
+    "./pid": "./src/pid/index.js",
+    "./nrmse": "./src/nrmse/index.js",
+    "./outliers": "./src/outliers/index.js"
   },
 
   "scripts": {
-    "test": "node test.js"
+    "test": "node --test test/ src/nrmse/errorMetric.test.js"
   },
   "repository": {
     "type": "git",
@@ -26,4 +32,4 @@
   ],
   "author": "Rene de Ren",
   "license": "SEE LICENSE"
-}
+}

scripts/wikiGen.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * wikiGen.js — shared wiki auto-generation helper for every EVOLV node.
+ *
+ * Two subcommands:
+ *
+ *   node wikiGen.js contract  <commands-module>     [--write <wiki-path>]
+ *   node wikiGen.js datamodel <specificClass-module> [--write <wiki-path>]
+ *
+ * `contract` walks the descriptor array exported by `src/commands/index.js`
+ * and emits a markdown table mapping canonical topic → aliases → payload
+ * schema → effect description.
+ *
+ * `datamodel` instantiates the domain with a minimal stub config, calls
+ * `getOutput()` once, and emits a markdown table of (key, type, sample value).
+ * If construction fails (because the domain needs a live runtime that isn't
+ * trivially stubbable), the script falls back to a hand-curated partial at
+ * `<repo>/wiki/_partial-datamodel.md.template` instead of crashing.
+ *
+ * When `--write <wiki-path>` is given, the output is spliced between the
+ * matching `<!-- BEGIN AUTOGEN: <marker> -->` / `<!-- END AUTOGEN: ... -->`
+ * markers in that file. Otherwise it prints to stdout.
+ *
+ * See `.claude/refactor/WIKI_TEMPLATE.md` (sections 5 and 8) and CONTRACTS.md
+ * for the canonical topic naming and registry shape this script consumes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ── CLI parsing ────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const [, , subcmd, target, ...rest] = argv;
+  const opts = { subcmd, target, write: null };
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--write' && rest[i + 1]) {
+      opts.write = rest[i + 1];
+      i++;
+    }
+  }
+  return opts;
+}
+
+function usage() {
+  process.stderr.write([
+    'Usage:',
+    '  node wikiGen.js contract  <path-to-commands/index.js>     [--write <wiki-path>]',
+    '  node wikiGen.js datamodel <path-to-specificClass.js>      [--write <wiki-path>]',
+    '',
+  ].join('\n'));
+}
+
+// ── Shared helpers ─────────────────────────────────────────────────────────
+
+function resolveAbs(p) {
+  return path.isAbsolute(p) ? p : path.resolve(process.cwd(), p);
+}
+
+function describeSchema(schema) {
+  if (!schema) return '_unspecified_';
+  const t = schema.type;
+  if (!t) return '_unspecified_';
+  if (t === 'any')    return '`any`';
+  if (t === 'object') {
+    const props = schema.properties || {};
+    const keys = Object.keys(props);
+    if (!keys.length) return '`object`';
+    const parts = keys.map((k) => {
+      const subType = props[k]?.type ?? 'any';
+      return `${k}:${subType}`;
+    });
+    return '`{ ' + parts.join(', ') + ' }`';
+  }
+  return '`' + t + '`';
+}
+
+function topicEffectFallback(topic) {
+  // Try to derive a short, plain-English effect from the canonical topic
+  // when the descriptor doesn't carry a description field. Keep it terse —
+  // a maintainer can override by adding `description` to the descriptor.
+  const prefixes = {
+    'set.':    'Replaces the named state value with the supplied payload.',
+    'cmd.':    'Triggers an action / sequence — not idempotent.',
+    'data.':   'Pushes a value into the node\'s measurement stream.',
+    'query.':  'Read-only query; node replies on the same msg.',
+    'child.':  'Parent/child plumbing — registers or unregisters a child node.',
+  };
+  for (const [pfx, line] of Object.entries(prefixes)) {
+    if (topic.startsWith(pfx)) return line;
+  }
+  return '_(see handler)_';
+}
+
+function spliceAutogen(filePath, marker, body) {
+  const begin = `<!-- BEGIN AUTOGEN: ${marker} -->`;
+  const end   = `<!-- END AUTOGEN: ${marker} -->`;
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`wikiGen: --write target '${filePath}' does not exist`);
+  }
+  const src = fs.readFileSync(filePath, 'utf8');
+  const bIdx = src.indexOf(begin);
+  const eIdx = src.indexOf(end);
+  if (bIdx < 0 || eIdx < 0 || eIdx < bIdx) {
+    throw new Error(`wikiGen: markers '${marker}' not found in ${filePath}`);
+  }
+  const before = src.slice(0, bIdx + begin.length);
+  const after  = src.slice(eIdx);
+  const out = before + '\n\n' + body.trimEnd() + '\n\n' + after;
+  fs.writeFileSync(filePath, out, 'utf8');
+}
+
+// ── Subcommand: contract ───────────────────────────────────────────────────
+
+function describeUnits(units) {
+  // Descriptor.units is the validated `{ measure, default }` pair the
+  // commandRegistry stores; render it as `<measure> (default <unit>)` so
+  // a reader sees both the dimension and the canonical default that the
+  // node coerces to. Em-dash for unit-less topics keeps the column tidy.
+  if (!units || typeof units !== 'object') return '—';
+  const { measure, default: def } = units;
+  if (!measure || !def) return '—';
+  return '`' + measure + '` (default `' + def + '`)';
+}
+
+function renderContract(commandsPath) {
+  const abs = resolveAbs(commandsPath);
+  // eslint-disable-next-line import/no-dynamic-require, global-require
+  const registry = require(abs);
+  if (!Array.isArray(registry)) {
+    throw new Error(`wikiGen contract: ${abs} does not export an array of descriptors`);
+  }
+
+  const lines = [];
+  lines.push('| Canonical topic | Aliases | Payload | Unit | Effect |');
+  lines.push('|---|---|---|---|---|');
+  for (const d of registry) {
+    const topic = '`' + d.topic + '`';
+    const aliases = (d.aliases && d.aliases.length)
+      ? d.aliases.map((a) => '`' + a + '`').join(', ')
+      : '_(none)_';
+    const payload = describeSchema(d.payloadSchema);
+    const unit = describeUnits(d.units);
+    const effect = d.description ? String(d.description) : topicEffectFallback(d.topic);
+    lines.push(`| ${topic} | ${aliases} | ${payload} | ${unit} | ${effect} |`);
+  }
+  return lines.join('\n');
+}
+
+// ── Subcommand: datamodel ──────────────────────────────────────────────────
+
+function inferSampleType(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+function trySampleValue(v) {
+  if (v === null || v === undefined) return '`null`';
+  const t = typeof v;
+  if (t === 'number' || t === 'boolean') return '`' + String(v) + '`';
+  if (t === 'string') return '`"' + v + '"`';
+  if (Array.isArray(v)) return '`[…]`';
+  if (t === 'object') return '`{…}`';
+  return '`' + String(v) + '`';
+}
+
+// Heuristic unit map for top-level snapshot keys that aren't structured as
+// MeasurementContainer keys (e.g. `heightBasin`, `surfaceArea`). Best-effort
+// — the canonical place for unit semantics is the node's config schema; the
+// table below is just enough to keep the auto-generated data-model readable.
+const FLAT_KEY_UNITS = {
+  heightBasin:     'm',
+  basinHeight:     'm',
+  inflowLevel:     'm',
+  outflowLevel:    'm',
+  overflowLevel:   'm',
+  startLevel:      'm',
+  stopLevel:       'm',
+  minLevel:        'm',
+  maxLevel:        'm',
+  surfaceArea:     'm2',
+  volEmptyBasin:   'm3',
+  maxVol:          'm3',
+  maxVolAtOverflow:'m3',
+  minVol:          'm3',
+  minVolAtInflow:  'm3',
+  minVolAtOutflow: 'm3',
+  percControl:     '%',
+  timeleft:        's',
+};
+
+function inferUnitFromKey(key) {
+  // MeasurementContainer-shaped keys take precedence: `{type}.{variant}.{position}.{childId}`.
+  const parts = key.split('.');
+  if (parts.length >= 3) {
+    const type = parts[0];
+    const map = {
+      flow:           'm3/s',
+      pressure:       'Pa',
+      power:          'W',
+      temperature:    'K',
+      level:          'm',
+      volume:         'm3',
+      volumePercent:  '%',
+      netFlowRate:    'm3/s',
+    };
+    if (map[type]) return map[type];
+  }
+  return FLAT_KEY_UNITS[key] || '—';
+}
+
+function renderDatamodel(specificClassPath) {
+  const abs = resolveAbs(specificClassPath);
+  // eslint-disable-next-line import/no-dynamic-require, global-require
+  const Domain = require(abs);
+
+  // Minimum viable stub config — the BaseDomain pipeline pulls per-key
+  // defaults from the JSON schema, so this only needs to supply the bits
+  // that BaseDomain reads from `userConfig` directly.
+  const stubConfig = {
+    general: {
+      name: `wikiGen-${Domain.name || 'domain'}`,
+      id: `wikiGen-${Domain.name || 'domain'}-id`,
+      logging: { enabled: false, logLevel: 'error' },
+    },
+  };
+
+  // Look for a hand-curated fallback alongside the wiki. Path is
+  // `<node>/wiki/_partial-datamodel.md.template` relative to the
+  // *commands*-or-specificClass file's repo root.
+  const repoRoot = findRepoRoot(abs);
+  const fallback = repoRoot
+    ? path.join(repoRoot, 'wiki', '_partial-datamodel.md.template')
+    : null;
+
+  let out;
+  try {
+    const instance = new Domain(stubConfig);
+    out = instance.getOutput ? instance.getOutput() : null;
+    if (!out || typeof out !== 'object') {
+      throw new Error('getOutput() returned a non-object');
+    }
+  } catch (err) {
+    process.stderr.write(`wikiGen datamodel: live instantiation failed: ${err.message}\n`);
+    if (fallback && fs.existsSync(fallback)) {
+      process.stderr.write(`wikiGen datamodel: using hand-curated fallback ${fallback}\n`);
+      return fs.readFileSync(fallback, 'utf8').trimEnd();
+    }
+    process.stderr.write('wikiGen datamodel: no hand-curated fallback found — emitting placeholder\n');
+    return [
+      '| Key | Type | Unit | Sample |',
+      '|---|---|---|---|',
+      `| _live instantiation failed; provide ${fallback ? `\`wiki/_partial-datamodel.md.template\`` : 'a hand-curated template'}_ | — | — | — |`,
+    ].join('\n');
+  }
+
+  const lines = [];
+  lines.push('| Key | Type | Unit | Sample |');
+  lines.push('|---|---|---|---|');
+  for (const k of Object.keys(out).sort()) {
+    const v = out[k];
+    lines.push(`| \`${k}\` | ${inferSampleType(v)} | ${inferUnitFromKey(k)} | ${trySampleValue(v)} |`);
+  }
+  return lines.join('\n');
+}
+
+function findRepoRoot(startPath) {
+  let dir = path.dirname(startPath);
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+// ── Entry point ────────────────────────────────────────────────────────────
+
+function main() {
+  const opts = parseArgs(process.argv);
+  if (!opts.subcmd || !opts.target) {
+    usage();
+    process.exit(1);
+  }
+
+  let body;
+  let marker;
+  if (opts.subcmd === 'contract') {
+    body = renderContract(opts.target);
+    marker = 'topic-contract';
+  } else if (opts.subcmd === 'datamodel') {
+    body = renderDatamodel(opts.target);
+    marker = 'data-model';
+  } else {
+    usage();
+    process.exit(1);
+  }
+
+  if (opts.write) {
+    spliceAutogen(resolveAbs(opts.write), marker, body);
+    process.stderr.write(`wikiGen: wrote ${marker} block into ${opts.write}\n`);
+  } else {
+    process.stdout.write(body + '\n');
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { renderContract, renderDatamodel, spliceAutogen, describeSchema, describeUnits };

src/configs/assetApiConfig.js

@@ -0,0 +1,16 @@
+const BASE_URL = 'http://localhost:8000';
+const AUTHORIZATION = '4a49332a-fc3e-11f0-bf0a-9457f8d645d9';
+const CSRF_TOKEN = 'dcWLY6luSVuQu4mIlKNCGlk3i9VzG9n3p2pxihcm';
+
+module.exports = {
+  baseUrl: BASE_URL,
+  registerPath: '/assets/store',
+  updatePath: (tag) => `/assets/${encodeURIComponent(tag)}/edit`,
+  updateMethod: 'POST',
+  headers: {
+    accept: 'application/json',
+    Authorization: AUTHORIZATION,
+    'Content-Type': 'application/json',
+    'X-CSRF-TOKEN': CSRF_TOKEN
+  }
+};

src/configs/diffuser.json

@@ -0,0 +1,163 @@
+{
+  "general": {
+    "name": {
+      "default": "Diffuser",
+      "rules": {
+        "type": "string",
+        "description": "A human-readable name for this diffuser zone."
+      }
+    },
+    "id": {
+      "default": null,
+      "rules": {
+        "type": "string",
+        "nullable": true,
+        "description": "Unique identifier for this diffuser node."
+      }
+    },
+    "unit": {
+      "default": "Nm3/h",
+      "rules": {
+        "type": "string",
+        "description": "Default airflow unit for this diffuser."
+      }
+    },
+    "logging": {
+      "logLevel": {
+        "default": "info",
+        "rules": {
+          "type": "enum",
+          "values": [
+            { "value": "debug", "description": "Verbose diagnostic messages." },
+            { "value": "info", "description": "General informational messages." },
+            { "value": "warn", "description": "Warning messages." },
+            { "value": "error", "description": "Error level messages only." }
+          ]
+        }
+      },
+      "enabled": {
+        "default": true,
+        "rules": {
+          "type": "boolean",
+          "description": "Enable or disable logging."
+        }
+      }
+    }
+  },
+  "asset": {
+    "model": {
+      "default": "gva-elastox-r",
+      "rules": {
+        "type": "string",
+        "description": "Asset model id resolved via assetResolver.resolve('curves', model). Selected from the asset-menu cascade in the editor; defaults to GVA ELASTOX-R for backward compatibility with the legacy hardcoded curve."
+      }
+    },
+    "assetTagNumber": {
+      "default": "",
+      "rules": {
+        "type": "string",
+        "description": "External asset registry tag number (e.g. Bedrijfsmiddelenregister), assigned by the asset-menu sync to the WBD asset API."
+      }
+    }
+  },
+  "functionality": {
+    "softwareType": {
+      "default": "diffuser",
+      "rules": {
+        "type": "string",
+        "description": "Software type identifier for parent-child registration."
+      }
+    },
+    "role": {
+      "default": "Aeration diffuser",
+      "rules": {
+        "type": "string",
+        "description": "Describes the functional role of this node."
+      }
+    },
+    "positionVsParent": {
+      "default": "atEquipment",
+      "rules": {
+        "type": "enum",
+        "values": [
+          { "value": "upstream", "description": "Upstream of parent equipment." },
+          { "value": "atEquipment", "description": "At equipment level." },
+          { "value": "downstream", "description": "Downstream of parent equipment." }
+        ]
+      }
+    }
+  },
+  "diffuser": {
+    "number": {
+      "default": 1,
+      "rules": {
+        "type": "number",
+        "description": "Sequential diffuser zone number."
+      }
+    },
+    "elements": {
+      "default": 1,
+      "rules": {
+        "type": "number",
+        "description": "Number of diffuser elements in the zone."
+      }
+    },
+    "membraneAreaPerElement": {
+      "default": null,
+      "rules": {
+        "type": "number",
+        "nullable": true,
+        "description": "Membrane area per element [m²] used to convert total airflow to canonical specific flux Nm³/(h·m² membrane) before curve lookup. Defaults to the selected curve's _meta.membraneArea_m2_per_element (Jäger 0.18, Sulzer 0.07, Aerostrip 1.0 normalisation). Set explicitly only to override the curve metadata."
+      }
+    },
+    "density": {
+      "default": 15,
+      "rules": {
+        "type": "number",
+        "description": "Bottom coverage [%] — fraction of the tank floor area occupied by diffuser membrane. Typical fine-bubble installs run 10–25 %. Used as the curve-family key in the supplier curve files (multi-coverage curves are interpolated; single-coverage curves are clamped). Replaces the legacy 'elements per m²' semantics, which was an incorrect re-tagging by an earlier refactor."
+      }
+    },
+    "waterHeight": {
+      "default": 0,
+      "rules": {
+        "type": "number",
+        "description": "Water column height above the diffuser."
+      }
+    },
+    "alfaFactor": {
+      "default": 0.7,
+      "rules": {
+        "type": "number",
+        "description": "Alpha factor used for oxygen transfer correction."
+      }
+    },
+    "headerPressure": {
+      "default": 0,
+      "rules": {
+        "type": "number",
+        "description": "Header gauge pressure above atmospheric (mbar)."
+      }
+    },
+    "localAtmPressure": {
+      "default": 1013.25,
+      "rules": {
+        "type": "number",
+        "description": "Local atmospheric pressure (mbar)."
+      }
+    },
+    "waterDensity": {
+      "default": 997,
+      "rules": {
+        "type": "number",
+        "description": "Water density used in head-pressure calculation (kg/m3)."
+      }
+    },
+    "zoneVolume": {
+      "default": 0,
+      "rules": {
+        "type": "number",
+        "description": "Aeration zone volume used to convert oxygen output to reactor OTR (m3)."
+      }
+    }
+  }
+}

src/configs/index.js

@@ -1,22 +1,52 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Current config version. All config JSONs should declare this version.
+ * Bump this when the config schema changes.
+ */
+const CURRENT_CONFIG_VERSION = '1.0.0';
+
 class ConfigManager {
     constructor(relPath = '.') {
         this.configDir = path.resolve(__dirname, relPath);
+
+        /**
+         * Migration functions keyed by "fromVersion->toVersion".
+         * Each function receives a config object and returns the migrated config.
+         *
+         * Example:
+         *   this.migrations['1.0.0->1.1.0'] = (config) => {
+         *       config.newSection = { enabled: false };
+         *       return config;
+         *   };
+         */
+        this.migrations = {};
     }
 
     /**
-     * Load a configuration file by name
+     * Load a configuration file by name.
+     * Automatically checks the config version and migrates if needed.
      * @param {string} configName - Name of the config file (without .json extension)
-     * @returns {Object} Parsed configuration object
+     * @returns {Object} Parsed configuration object (migrated to current version if necessary)
      */
     getConfig(configName) {
         try {
             const configPath = path.resolve(this.configDir, `${configName}.json`);
             const configData = fs.readFileSync(configPath, 'utf8');
-            return JSON.parse(configData);
+            let config = JSON.parse(configData);
+
+            // Auto-migrate if version is behind current
+            const configVersion = config.version || '0.0.0';
+            if (configVersion !== CURRENT_CONFIG_VERSION) {
+                config = this.migrateConfig(config, configVersion, CURRENT_CONFIG_VERSION);
+            }
+
+            return config;
         } catch (error) {
+            if (error.message && error.message.startsWith('Failed to load config')) {
+                throw error;
+            }
             throw new Error(`Failed to load config '${configName}': ${error.message}`);
         }
     }
@@ -79,26 +109,86 @@ class ConfigManager {
             functionality: {
                 softwareType: nodeName.toLowerCase(),
                 positionVsParent: uiConfig.positionVsParent || 'atEquipment',
-                distance: uiConfig.hasDistance ? uiConfig.distance : undefined
+                distance: uiConfig.hasDistance ? uiConfig.distance : null
+            },
+            output: {
+                process: uiConfig.processOutputFormat || 'process',
+                dbase: uiConfig.dbaseOutputFormat || 'influxdb'
             }
         };
 
-        // Add asset section if UI provides asset fields
-        if (uiConfig.supplier || uiConfig.category || uiConfig.assetType || uiConfig.model) {
-            config.asset = {
-                uuid: uiConfig.uuid || uiConfig.assetUuid || null,
-                tagCode: uiConfig.tagCode || uiConfig.assetTagCode || null,
-                supplier: uiConfig.supplier || 'Unknown',
-                category: uiConfig.category || 'sensor',
-                type: uiConfig.assetType || 'Unknown',
-                model: uiConfig.model || 'Unknown',
-                unit: uiConfig.unit || 'unitless'
-            };
+        // Asset section is emitted per-key: only fields the editor actually
+        // set propagate to the domain config. Schemas that omit a key (e.g.
+        // rotatingMachine deliberately drops asset.supplier/category/type
+        // because those come from the asset registry at runtime) no longer
+        // get those keys injected and then stripped by ValidationUtils with
+        // a warning. Empty strings from HTML defaults stay falsy → omitted →
+        // schema default applies.
+        const asset = {};
+        const uuid = uiConfig.uuid || uiConfig.assetUuid;
+        const tagCode = uiConfig.tagCode || uiConfig.assetTagCode;
+        if (uuid) asset.uuid = uuid;
+        if (tagCode) asset.tagCode = tagCode;
+        if (uiConfig.supplier) asset.supplier = uiConfig.supplier;
+        if (uiConfig.category) asset.category = uiConfig.category;
+        if (uiConfig.assetType) asset.type = uiConfig.assetType;
+        if (uiConfig.model) asset.model = uiConfig.model;
+        if (uiConfig.unit) asset.unit = uiConfig.unit;
+        if (Object.keys(asset).length > 0) config.asset = asset;
+
+        // Merge domain-specific sections. Must be a DEEP merge: domainConfig
+        // commonly returns subsets of `general` / `asset` (e.g. {general:
+        // {unit}}, {asset: {curveUnits}}) and a shallow assign would wipe out
+        // sibling keys this method just populated — notably `general.id`
+        // (nodeId) and `asset.model`, causing child-registration id collisions
+        // and curve-lookup failures downstream.
+        ConfigManager._deepMerge(config, domainConfig);
+
+        return config;
+    }
+
+    static _isPlainObject(v) {
+        return Object.prototype.toString.call(v) === '[object Object]';
+    }
+
+    /**
+     * In-place recursive merge. Arrays and primitives in `src` replace `dst`;
+     * plain objects are merged key-by-key so siblings on `dst` survive.
+     */
+    static _deepMerge(dst, src) {
+        if (!ConfigManager._isPlainObject(src)) return dst;
+        for (const key of Object.keys(src)) {
+            const v = src[key];
+            if (Array.isArray(v)) {
+                dst[key] = [...v];
+            } else if (ConfigManager._isPlainObject(v)) {
+                if (!ConfigManager._isPlainObject(dst[key])) dst[key] = {};
+                ConfigManager._deepMerge(dst[key], v);
+            } else {
+                dst[key] = v;
+            }
+        }
+        return dst;
+    }
+
+    /**
+     * Migrate a config object from one version to another by applying
+     * registered migration functions in sequence.
+     * @param {object} config - The config object to migrate
+     * @param {string} fromVersion - Current version of the config
+     * @param {string} toVersion - Target version
+     * @returns {object} Migrated config with updated version field
+     */
+    migrateConfig(config, fromVersion, toVersion) {
+        const migrationKey = `${fromVersion}->${toVersion}`;
+        const migrationFn = this.migrations[migrationKey];
+
+        if (migrationFn) {
+            config = migrationFn(config);
         }
 
-        // Merge domain-specific sections
-        Object.assign(config, domainConfig);
-
+        // Stamp the current version so it won't re-migrate
+        config.version = toVersion;
         return config;
     }
 
@@ -110,30 +200,30 @@ class ConfigManager {
         return this.getConfig('baseConfig');
     }
 
-        createEndpoint(nodeName) {
-            try {
-                // Load the config for this node
-                const config = this.getConfig(nodeName);
-                
-                // Convert config to JSON
-                const configJSON = JSON.stringify(config, null, 2);
+    createEndpoint(nodeName) {
+        try {
+            // Load the config for this node
+            const config = this.getConfig(nodeName);
 
-                // Assemble the complete script
-                return `
-                // Create the namespace structure
-                window.EVOLV = window.EVOLV || {};
-                window.EVOLV.nodes = window.EVOLV.nodes || {};
-                window.EVOLV.nodes.${nodeName} = window.EVOLV.nodes.${nodeName} || {};
+            // Convert config to JSON
+            const configJSON = JSON.stringify(config, null, 2);
 
-                // Inject the pre-loaded config data directly into the namespace
-                window.EVOLV.nodes.${nodeName}.config = ${configJSON};
+            // Assemble the complete script
+            return `
+            // Create the namespace structure
+            window.EVOLV = window.EVOLV || {};
+            window.EVOLV.nodes = window.EVOLV.nodes || {};
+            window.EVOLV.nodes.${nodeName} = window.EVOLV.nodes.${nodeName} || {};
 
-                console.log('${nodeName} config loaded and endpoint created');
-                `;
-            } catch (error) {
-                throw new Error(`Failed to create endpoint for '${nodeName}': ${error.message}`);
-            }
+            // Inject the pre-loaded config data directly into the namespace
+            window.EVOLV.nodes.${nodeName}.config = ${configJSON};
+
+            console.log('${nodeName} config loaded and endpoint created');
+            `;
+        } catch (error) {
+            throw new Error(`Failed to create endpoint for '${nodeName}': ${error.message}`);
         }
+    }
 }
 
-module.exports = ConfigManager;
+module.exports = ConfigManager;

src/configs/machineGroupControl.json

@@ -91,7 +91,72 @@
                 ],
                 "description": "Defines the position of the measurement relative to its parent equipment or system."
             }
+        },
+      "distance": {
+        "default": null,
+        "rules": {
+          "type": "number",
+          "nullable": true,
+          "description": "Optional spatial offset from the parent equipment reference. Populated from the editor when hasDistance is enabled; null otherwise."
         }
+      },
+      "distanceUnit": {
+        "default": "m",
+        "rules": {
+          "type": "string",
+          "description": "Unit for the functionality.distance offset (e.g. 'm', 'cm')."
+        }
+      },
+      "distanceDescription": {
+        "default": "",
+        "rules": {
+          "type": "string",
+          "description": "Free-text description of what the distance offset represents."
+        }
+      }
+    },
+    "output": {
+      "process": {
+        "default": "process",
+        "rules": {
+          "type": "enum",
+          "values": [
+            { "value": "process", "description": "Delta-compressed process message (default)." },
+            { "value": "json", "description": "Raw JSON payload." },
+            { "value": "csv", "description": "CSV-formatted payload." }
+          ],
+          "description": "Format of the process payload emitted on output port 0."
+        }
+      },
+      "dbase": {
+        "default": "influxdb",
+        "rules": {
+          "type": "enum",
+          "values": [
+            { "value": "influxdb", "description": "InfluxDB line-protocol payload (default)." },
+            { "value": "frost", "description": "FROST/SensorThings CoreSync payload." },
+            { "value": "json", "description": "Raw JSON payload." },
+            { "value": "csv", "description": "CSV-formatted payload." }
+          ],
+          "description": "Format of the telemetry payload emitted on output port 1."
+        }
+      }
+    },
+    "planner": {
+      "useRendezvous": {
+        "default": true,
+        "rules": {
+          "type": "boolean",
+          "description": "If true, every dispatch is routed through the rendezvous planner regardless of control strategy: per-pump moves are delayed so all pumps reach their setpoint at the same wall-clock instant t* = max(eta_i). If false, all flowmovement commands fire immediately and each pump ramps at its own speed (legacy behaviour)."
+        }
+      },
+      "emergencyPressurePa": {
+        "default": null,
+        "rules": {
+          "type": "number",
+          "description": "Safety threshold (canonical Pa) for the rendezvous emergency bypass. While a rendezvous is in flight new setpoints are locked out and queued sequentially; if the resolved header pressure reaches this value the lock is pre-empted and the group re-plans immediately. Null/unset (the default) leaves the bypass mechanism wired but INERT — it never fires until a real threshold is configured."
+        }
+      }
     },
     "mode": {
         "current": {
@@ -107,10 +172,6 @@
                 "value": "priorityControl",
                 "description": "Machines are controlled sequentially from minimum to maximum output until each is maxed out, then additional machines are added."
               },
-              {
-                "value": "prioritypercentagecontrol",
-                "description": "Machines are controlled sequentially from minimum to maximum output until each is maxed out, then additional machines are added based on a percentage of the total demand."
-              },
               {
                 "value": "maintenance",
                 "description": "The group is in maintenance mode with limited actions (monitoring only)."
@@ -140,14 +201,6 @@
                   "description": "Actions allowed in priorityControl mode."
                 }
               },
-              "prioritypercentagecontrol": {
-                "default": ["statusCheck", "execSequentialControl", "balanceLoad", "emergencyStop"],
-                "rules": {
-                  "type": "set",
-                  "itemType": "string",
-                  "description": "Actions allowed in manualOverride mode."
-                }
-              },
               "maintenance": {
                 "default": ["statusCheck"],
                 "rules": {
@@ -165,7 +218,7 @@
           "rules": {
             "type": "object",
             "schema": {
-              "optimalcontrol": {
+              "optimalControl": {
                 "default": ["parent", "GUI", "physical", "API"],
                 "rules": {
                   "type": "set",
@@ -173,7 +226,7 @@
                   "description": "Command sources allowed in optimalControl mode."
                 }
               },
-              "prioritycontrol": {
+              "priorityControl": {
                 "default": ["parent", "GUI", "physical", "API"],
                 "rules": {
                   "type": "set",
@@ -181,36 +234,17 @@
                   "description": "Command sources allowed in priorityControl mode."
                 }
               },
-              "prioritypercentagecontrol": {
-                "default": ["parent", "GUI", "physical", "API"],
+              "maintenance": {
+                "default": ["parent", "GUI"],
                 "rules": {
                   "type": "set",
                   "itemType": "string",
-                  "description": "Command sources allowed "
+                  "description": "Command sources allowed in maintenance mode. Status/inspection only — physical/HMI and API writes are dropped."
                 }
               }
             },
             "description": "Specifies the valid command sources recognized by the machine group controller for each mode."
           }
         }
-    },
-    "scaling": {
-      "current": {
-        "default": "normalized",
-        "rules": {
-          "type": "enum",
-          "values": [
-            {
-              "value": "normalized",
-              "description": "Scales the demand between 0–100% of the total flow capacity, interpolating to calculate the effective demand."
-            },
-            {
-              "value": "absolute",
-              "description": "Uses the absolute demand value directly, capped between the min and max machine flow capacities."
-            }
-          ],
-          "description": "The scaling mode for demand calculations."
-        }
-      }
     }
   }

src/configs/measurement.json

@@ -96,10 +96,38 @@
             "default": null,
             "rules": {
                 "type": "number",
+                "nullable": true,
                 "description": "Defines the position of the measurement relative to its parent equipment or system."
             }
         }
     },
+    "output": {
+        "process": {
+            "default": "process",
+            "rules": {
+                "type": "enum",
+                "values": [
+                    { "value": "process", "description": "Delta-compressed process message (default)." },
+                    { "value": "json", "description": "Raw JSON payload." },
+                    { "value": "csv", "description": "CSV-formatted payload." }
+                ],
+                "description": "Format of the process payload emitted on output port 0."
+            }
+        },
+        "dbase": {
+            "default": "influxdb",
+            "rules": {
+                "type": "enum",
+                "values": [
+                    { "value": "influxdb", "description": "InfluxDB line-protocol payload (default)." },
+                    { "value": "frost", "description": "FROST/SensorThings CoreSync payload." },
+                    { "value": "json", "description": "Raw JSON payload." },
+                    { "value": "csv", "description": "CSV-formatted payload." }
+                ],
+                "description": "Format of the telemetry payload emitted on output port 1."
+            }
+        }
+    },
     "asset": {
         "uuid": {
             "default": null,
@@ -117,6 +145,14 @@
                 "description": "Asset tag code which is a unique identifier for this asset. May be null if not assigned."
             }
         },
+        "tagNumber": {
+            "default": null,
+            "rules": {
+                "type": "string",
+                "nullable": true,
+                "description": "Asset tag number assigned by the asset registry. May be null if not assigned."
+            }
+        },
         "geoLocation": {
             "default": {
                 "x": 0,
@@ -166,6 +202,10 @@
                     {
                         "value": "sensor",
                         "description": "A device that detects or measures a physical property and responds to it (e.g. temperature sensor)."
+                    },
+                    {
+                        "value": "measurement",
+                        "description": "Measurement software category used by the asset menu for this node."
                     }
                 ]
             }
@@ -208,6 +248,52 @@
             }
         }
     },
+    "assetRegistration": {
+        "default": {
+            "profileId": 1,
+            "locationId": 1,
+            "processId": 1,
+            "status": "actief",
+            "childAssets": []
+        },
+        "rules": {
+            "type": "object",
+            "schema": {
+                "profileId": {
+                    "default": 1,
+                    "rules": {
+                        "type": "number"
+                    }
+                },
+                "locationId": {
+                    "default": 1,
+                    "rules": {
+                        "type": "number"
+                    }
+                },
+                "processId": {
+                    "default": 1,
+                    "rules": {
+                        "type": "number"
+                    }
+                },
+                "status": {
+                    "default": "actief",
+                    "rules": {
+                        "type": "string"
+                    }
+                },
+                "childAssets": {
+                    "default": [],
+                    "rules": {
+                        "type": "array",
+                        "itemType": "string",
+                        "minLength": 0
+                    }
+                }
+            }
+        }
+    },
     "scaling": {
         "enabled": {
             "default": false,
@@ -353,6 +439,44 @@
             }
         }
     },
+    "mode": {
+        "current": {
+            "default": "analog",
+            "rules": {
+                "type": "enum",
+                "values": [
+                    {
+                        "value": "analog",
+                        "description": "Single-scalar input mode (classic 4-20mA / PLC style). msg.payload is a number; the node runs one offset/scaling/smoothing/outlier pipeline and emits one MeasurementContainer slot."
+                    },
+                    {
+                        "value": "digital",
+                        "description": "Multi-channel input mode (MQTT / IoT JSON style). msg.payload is an object keyed by channel names declared under config.channels; the node routes each key through its own pipeline and emits N slots from one input message."
+                    }
+                ],
+                "description": "Selects how incoming msg.payload is interpreted."
+            }
+        }
+    },
+    "channels": {
+        "default": [],
+        "rules": {
+            "type": "array",
+            "itemType": "object",
+            "minLength": 0,
+            "description": "Channel map used in digital mode. Each entry is a self-contained pipeline definition: {key, type, position, unit, scaling?, smoothing?, outlierDetection?, distance?}. Ignored in analog mode."
+        }
+    },
+    "calibration": {
+        "stabilityThreshold": {
+            "default": 0.01,
+            "rules": {
+                "type": "number",
+                "min": 0,
+                "description": "Absolute standard-deviation ceiling (in scaling-units, i.e. the same range as absMin..absMax) below which the rolling window is considered stable enough to trust for calibration / repeatability. A buffer with stdDev <= threshold is treated as stable; anything above aborts calibrate() and evaluateRepeatability() with a warning. Default 0.01 fits the [50,100] absMin/absMax default range; tighten or relax to match your sensor's expected noise floor."
+            }
+        }
+    },
     "outlierDetection": {
         "enabled": {
             "default": false,
@@ -389,4 +513,4 @@
             }
         }
     }
-}
+}

src/configs/monster.json

@@ -0,0 +1,284 @@
+{
+    "general": {
+        "name": {
+            "default": "Monster Configuration",
+            "rules": {
+                "type": "string",
+                "description": "A human-readable name or label for this configuration."
+            }
+        },
+        "id": {
+            "default": null,
+            "rules": {
+                "type": "string",
+                "nullable": true,
+                "description": "A unique identifier for this configuration. If not provided, defaults to null."
+            }
+        },
+        "unit": {
+            "default": "unitless",
+            "rules": {
+                "type": "string",
+                "description": "The unit for this configuration (e.g., 'meters', 'seconds', 'unitless')."
+            }
+        },
+        "logging": {
+            "logLevel": {
+                "default": "info",
+                "rules": {
+                    "type": "enum",
+                    "values": [
+                        {
+                            "value": "debug",
+                            "description": "Log messages are printed for debugging purposes."
+                        },
+                        {
+                            "value": "info",
+                            "description": "Informational messages are printed."
+                        },
+                        {
+                            "value": "warn",
+                            "description": "Warning messages are printed."
+                        },
+                        {
+                            "value": "error",
+                            "description": "Error messages are printed."
+                        }
+                    ]
+                }
+            },
+            "enabled": {
+                "default": true,
+                "rules": {
+                    "type": "boolean",
+                    "description": "Indicates whether logging is active. If true, log messages will be generated."
+                }
+            }
+        }
+    },
+    "functionality": {
+        "softwareType": {
+            "default": "monster",
+            "rules": {
+                "type": "string",
+                "description": "Specified software type for this configuration."
+            }
+        },
+        "role": {
+            "default": "samplingCabinet",
+            "rules": {
+                "type": "string",
+                "description": "Indicates the role this configuration plays (e.g., sensor, controller, etc.)."
+            }
+        }
+    },
+    "asset": {
+        "uuid": {
+            "default": null,
+            "rules": {
+                "type": "string",
+                "nullable": true,
+                "description": "Asset tag number which is a universally unique identifier for this asset. May be null if not assigned."
+            }
+        },
+        "geoLocation": {
+            "default": {
+                "x": 0,
+                "y": 0,
+                "z": 0
+            },
+            "rules": {
+                "type": "object",
+                "description": "An object representing the asset's physical coordinates or location.",
+                "schema": {
+                    "x": {
+                        "default": 0,
+                        "rules": {
+                            "type": "number",
+                            "description": "X coordinate of the asset's location."
+                        }
+                    },
+                    "y": {
+                        "default": 0,
+                        "rules": {
+                            "type": "number",
+                            "description": "Y coordinate of the asset's location."
+                        }
+                    },
+                    "z": {
+                        "default": 0,
+                        "rules": {
+                            "type": "number",
+                            "description": "Z coordinate of the asset's location."
+                        }
+                    }
+                }
+            }
+        },
+        "supplier": {
+            "default": "Unknown",
+            "rules": {
+                "type": "string",
+                "description": "The supplier or manufacturer of the asset."
+            }
+        },
+        "type": {
+            "default": "sensor",
+            "rules": {
+                "type": "enum",
+                "values": [
+                    {
+                        "value": "sensor",
+                        "description": "A device that detects or measures a physical property and responds to it (e.g. temperature sensor)."
+                    }
+                ]
+            }
+        },
+        "subType": {
+            "default": "pressure",
+            "rules": {
+                "type": "string",
+                "description": "A more specific classification within 'type'. For example, 'pressure' for a pressure sensor."
+            }
+        },
+        "model": {
+            "default": "Unknown",
+            "rules": {
+                "type": "string",
+                "description": "A user-defined or manufacturer-defined model identifier for the asset."
+            }
+        },
+        "emptyWeightBucket": {
+            "default": 3,
+            "rules": {
+                "type": "number",
+                "description": "The weight of the empty bucket in kilograms."
+            }
+        }
+    },
+    "constraints": {
+        "samplingtime": {
+            "default": 0,
+            "rules": {
+                "type": "number",
+                "description": "The time interval between sampling events (in seconds) if not using a flow meter."
+            }
+        },
+        "samplingperiod": {
+            "default": 24,
+            "rules": {
+                "type": "number",
+                "description": "The fixed period in hours in which a composite sample is collected."
+            }
+        },
+        "minVolume": {
+            "default": 5,
+            "rules": {
+                "type": "number",
+                "min": 5,
+                "description": "The minimum volume in liters."
+            }
+        },
+        "maxWeight": {
+            "default": 23,
+            "rules": {
+                "type": "number",
+                "max": 23,
+                "description": "The maximum weight in kilograms."
+            }
+        },
+        "subSampleVolume": {
+            "default": 50,
+            "rules": {
+                "type": "number",
+                "min": 50,
+                "max": 50,
+                "description": "The volume of each sub-sample in milliliters."
+            }
+        },
+        "storageTemperature": {
+            "default": {
+                "min": 1,
+                "max": 5
+            },
+            "rules": {
+                "type": "object",
+                "description": "Acceptable storage temperature range for samples in degrees Celsius.",
+                "schema": {
+                    "min": {
+                        "default": 1,
+                        "rules": {
+                            "type": "number",
+                            "min": 1,
+                            "description": "Minimum acceptable storage temperature in degrees Celsius."
+                        }
+                    },
+                    "max": {
+                        "default": 5,
+                        "rules": {
+                            "type": "number",
+                            "max": 5,
+                            "description": "Maximum acceptable storage temperature in degrees Celsius."
+                        }
+                    }
+                }
+            }
+        },
+        "flowmeter": {
+            "default": true,
+            "rules": {
+                "type": "boolean",
+                "description": "Indicates whether a flow meter is used for proportional sampling."
+            }
+        },
+        "closedSystem": {
+            "default": false,
+            "rules": {
+                "type": "boolean",
+                "description": "Indicates if the sampling system is closed (true) or open (false)."
+            }
+        },
+        "intakeSpeed": {
+            "default": 0.3,
+            "rules": {
+                "type": "number",
+                "description": "Minimum intake speed in meters per second."
+            }
+        },
+        "intakeDiameter": {
+            "default": 12,
+            "rules": {
+                "type": "number",
+                "description": "Minimum inner diameter of the intake tubing in millimeters."
+            }
+        },
+        "nominalFlowMin": {
+            "default": 0,
+            "rules": {
+                "type": "number",
+                "description": "Lower bound of expected inflow rate (m3/h). Used together with flowMax to scale the rain-driven flow prediction."
+            }
+        },
+        "flowMax": {
+            "default": 0,
+            "rules": {
+                "type": "number",
+                "description": "Upper bound of expected inflow rate (m3/h). Used together with nominalFlowMin to scale the rain-driven flow prediction."
+            }
+        },
+        "maxRainRef": {
+            "default": 10,
+            "rules": {
+                "type": "number",
+                "description": "Reference rain index that maps to the flowMax end of the prediction band."
+            }
+        },
+        "minSampleIntervalSec": {
+            "default": 60,
+            "rules": {
+                "type": "number",
+                "description": "Cooldown between consecutive sample pulses (seconds). Pulses raised faster than this are recorded as missedSamples."
+            }
+        }
+    }
+}

src/configs/pumpingStation.json

@@ -22,6 +22,14 @@
                 "description": "The default flow unit used for reporting station throughput."
             }
         },
+        "flowThreshold": {
+            "default": 0.0001,
+            "rules": {
+                "type": "number",
+                "min": 0,
+                "description": "Flow dead-band in m3/s below which the station treats net flow as steady."
+            }
+        },
         "logging": {
             "logLevel": {
                 "default": "info",
@@ -93,6 +101,14 @@
                 ]
             }
         },
+        "distance": {
+            "default": null,
+            "rules": {
+                "type": "number",
+                "nullable": true,
+                "description": "Optional distance to parent asset for registration metadata."
+            }
+        },
         "tickIntervalMs": {
             "default": 1000,
             "rules": {
@@ -119,6 +135,54 @@
             }
         }
     },
+    "output": {
+        "process": {
+            "default": "process",
+            "rules": {
+                "type": "enum",
+                "values": [
+                    {
+                        "value": "process",
+                        "description": "Delta-compressed process message."
+                    },
+                    {
+                        "value": "json",
+                        "description": "JSON payload."
+                    },
+                    {
+                        "value": "csv",
+                        "description": "CSV-formatted payload."
+                    }
+                ],
+                "description": "Format of the process payload emitted on output port 0."
+            }
+        },
+        "dbase": {
+            "default": "influxdb",
+            "rules": {
+                "type": "enum",
+                "values": [
+                    {
+                        "value": "influxdb",
+                        "description": "InfluxDB telemetry payload."
+                    },
+                    {
+                        "value": "frost",
+                        "description": "FROST/SensorThings CoreSync payload."
+                    },
+                    {
+                        "value": "json",
+                        "description": "JSON payload."
+                    },
+                    {
+                        "value": "csv",
+                        "description": "CSV-formatted payload."
+                    }
+                ],
+                "description": "Format of the telemetry payload emitted on output port 1."
+            }
+        }
+    },
     "asset": {
         "uuid": {
             "default": null,
@@ -207,14 +271,14 @@
     },
     "basin": {
         "volume": {
-            "default": "1",
+            "default": 50,
             "rules": {
                 "type": "number",
                 "description": "Total volume of empty basin in m3"
             }
         },
         "height": {
-            "default": "1",
+            "default": 4,
             "rules": {
                 "type": "number",
                 "description": "Total height of basin in m"
@@ -227,24 +291,24 @@
                 "description": "Unit used for level related setpoints and thresholds."
             }
         },
-        "heightInlet": {
-            "default": 2,
+        "inflowLevel": {
+            "default": 1.5,
             "rules": {
                 "type": "number",
                 "min": 0,
-                "description": "Height of the inlet pipe measured from the basin floor (m)."
+                "description": "Bottom/invert height of the inlet pipe measured from the basin floor (m). Acts as the ramp foot in levelbased control: demand stays at 0 % below inflowLevel and scales 0 → 100 % across [inflowLevel, maxLevel]."
             }
         },
-        "heightOutlet": {
+        "outflowLevel": {
             "default": 0.2,
             "rules": {
                 "type": "number",
                 "min": 0,
-                "description": "Height of the outlet pipe measured from the basin floor (m)."
+                "description": "Top height of the outlet or pump-suction pipe measured from the basin floor (m)."
             }
         },
-        "heightOverflow": {
-            "default": 2.5,
+        "overflowLevel": {
+            "default": 3.8,
             "rules": {
                 "type": "number",
                 "min": 0,
@@ -299,6 +363,30 @@
                 "description": "Reference height to use to identify the height vs other basins with. This will say something more about the expected pressure loss in m head"
             }
         },
+        "minHeightBasedOn": {
+            "default": "outlet",
+            "rules": {
+                "type": "enum",
+                "values": [
+                    {
+                        "value": "inlet",
+                        "description": "Minimum height is based on inlet elevation."
+                    },
+                    {
+                        "value": "outlet",
+                        "description": "Minimum height is based on outlet elevation."
+                    }
+                ],
+                "description": "Basis for minimum height check: inlet or outlet."
+            }
+        },
+        "basinBottomRef": {
+            "default": 0,
+            "rules": {
+                "type": "number",
+                "description": "Absolute elevation reference of basin bottom."
+            }
+        },
         "staticHead": {
             "default": 12,
             "rules": {
@@ -348,13 +436,13 @@
         }
     },
     "control": {
-        "controlStrategy": {
-            "default": "levelBased",
+        "mode": {
+            "default": "levelbased",
             "rules": {
-                "type": "enum",
+                "type": "string",
                 "values": [
                     {
-                        "value": "levelBased",
+                        "value": "levelbased",
                         "description": "Lead and lag pumps are controlled by basin level thresholds."
                     },
                     {
@@ -362,9 +450,21 @@
                         "description": "Pumps target a discharge pressure setpoint."
                     },
                     {
-                        "value": "flowTracking",
+                        "value": "flowBased",
                         "description": "Pumps modulate to match measured inflow or downstream demand."
                     },
+                    {
+                        "value": "percentageBased",
+                        "description": "Pumps operate to maintain basin volume at a target percentage."
+                    },
+                    {
+                        "value":"powerBased",
+                        "description": "Pumps are controlled based on power consumption.For example, to limit peak power usage or operate within netcongestion limits."
+                    },
+                    {
+                        "value": "hybrid",
+                        "description": "Combines multiple control strategies for optimized operation."
+                    },
                     {
                         "value": "manual",
                         "description": "Pumps are operated manually or by an external controller."
@@ -373,94 +473,267 @@
                 "description": "Primary control philosophy for pump actuation."
             }
         },
-        "levelSetpoints": {
-            "default": {
-                "startLeadPump": 1.2,
-                "stopLeadPump": 0.8,
-                "startLagPump": 1.8,
-                "stopLagPump": 1.4,
-                "alarmHigh": 2.3,
-                "alarmLow": 0.3
-            },
+        "allowedModes": {
+            "default": [
+                "levelbased",
+                "pressurebased",
+                "flowbased",
+                "percentagebased",
+                "powerbased",
+                "manual"
+            ],
             "rules": {
-                "type": "object",
-                "description": "Level thresholds that govern pump staging and alarms (m).",
-                "schema": {
-                    "startLeadPump": {
-                        "default": 1.2,
-                        "rules": {
-                            "type": "number",
-                            "description": "Level that starts the lead pump."
+                "type": "set",
+                "itemType": "string",
+                "description": "List of control modes that the station is permitted to operate in."
+            }
+        },
+        "levelbased": {
+            "minLevel": {
+                "default": 0.3,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Below this level the MGC shuts down all pumps (unconditional stop). Between minLevel and the active ramp start, demand is held at 0 %."
+                }
+            },
+            "startLevel": {
+                "default": 1,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Pump-on threshold (rising-edge engagement). Pumps stay off below startLevel until level rises through it; once engaged they remain on until level drops through stopLevel (falling-edge). Also serves as the bottom of the held-then-ramp curve during draining when enableShiftedRamp is on. Independent of basin geometry: NOT clamped against inflowLevel."
+                }
+            },
+            "stopLevel": {
+                "default": null,
+                "rules": {
+                    "type": "number",
+                    "nullable": true,
+                    "min": 0,
+                    "description": "Optional pump-off threshold. When set, PS sends an explicit turnOffAllMachines command to MGC the moment level drops below stopLevel. Does NOT shape the ramp. Pair with a startLevel above stopLevel to get hysteresis (engage at startLevel rising, disengage at stopLevel falling). Must be ≥ minLevel and ≤ startLevel. NOTE: schema default stays null so omitting stopLevel keeps the hysteresis inactive; the editor HTML provides a realistic 0.5 m default for drag-in UX."
+                }
+            },
+            "holdLevel": {
+                "default": null,
+                "rules": {
+                    "type": "number",
+                    "nullable": true,
+                    "min": 0,
+                    "description": "Optional `0 %` ramp foot. When set, pumps engage at startLevel but hold at 0 % (= flow.min via MGC) across [startLevel, holdLevel], then ramp 0 → 100 % across [holdLevel, maxLevel]. Default null → equals startLevel, i.e. no hold band and the ramp starts immediately at startLevel. Must satisfy startLevel ≤ holdLevel ≤ maxLevel."
+                }
+            },
+            "deadZoneKeepAlivePercent": {
+                "default": 1,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "max": 100,
+                    "description": "Percent emitted to MGC across the falling-edge keep-alive band [stopLevel, startLevel] (i.e. once engaged, while draining back below startLevel but still above stopLevel). 0 maps to flow.min; the 1 % default sits just above min so MGC keeps at least one pump rotating instead of resting at the absolute minimum."
+                }
+            },
+            "maxLevel": {
+                "default": 3.8,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Level at which the pump demand saturates at 100 %. Above this, demand stays clamped."
+                }
+            },
+            "curveType": {
+                "default": "linear",
+                "rules": {
+                    "type": "enum",
+                    "values": [
+                        {
+                            "value": "linear",
+                            "description": "Linear demand scaling between the active lower ramp level and maxLevel."
+                        },
+                        {
+                            "value": "log",
+                            "description": "Logarithmic demand scaling with fast response early in the ramp."
                         }
-                    },
-                    "stopLeadPump": {
-                        "default": 0.8,
-                        "rules": {
-                            "type": "number",
-                            "description": "Level that stops the lead pump."
-                        }
-                    },
-                    "startLagPump": {
-                        "default": 1.8,
-                        "rules": {
-                            "type": "number",
-                            "description": "Level that starts the lag pump."
-                        }
-                    },
-                    "stopLagPump": {
-                        "default": 1.4,
-                        "rules": {
-                            "type": "number",
-                            "description": "Level that stops the lag pump."
-                        }
-                    },
-                    "alarmHigh": {
-                        "default": 2.3,
-                        "rules": {
-                            "type": "number",
-                            "description": "High level alarm threshold."
-                        }
-                    },
-                    "alarmLow": {
-                        "default": 0.3,
-                        "rules": {
-                            "type": "number",
-                            "description": "Low level alarm threshold."
-                        }
-                    }
+                    ],
+                    "description": "Demand curve used by levelbased control."
+                }
+            },
+            "logCurveFactor": {
+                "default": 9,
+                "rules": {
+                    "type": "number",
+                    "min": 0.001,
+                    "description": "Shape factor for the levelbased log curve; higher values increase early response."
+                }
+            },
+            "enableShiftedRamp": {
+                "default": false,
+                "rules": {
+                    "type": "boolean",
+                    "description": "When true, arm a hysteresis shift: once level rises past shiftLevel the ramp foot moves left from inflowLevel to startLevel until level falls back below startLevel."
+                }
+            },
+            "shiftLevel": {
+                "default": 0,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Level (m) at which the held output starts ramping down during draining. Must be > startLevel and ≤ maxLevel. Ignored when enableShiftedRamp is false."
+                }
+            },
+            "shiftArmPercent": {
+                "default": 95,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "max": 100,
+                    "description": "Output % threshold that arms the shift on the way up. Once armed, the output value at the moment direction flips to draining becomes the held value, and stays held until level drops to shiftLevel. Disarms when level reaches startLevel."
                 }
             }
         },
-        "pressureSetpoint": {
-            "default": 250,
-            "rules": {
-                "type": "number",
-                "min": 0,
-                "description": "Target discharge pressure when operating in pressure control (kPa)."
+        "pressureBased": {
+            "pressureSetpoint": {
+                "default": 1000,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "max": 5000,
+                    "description": "Target discharge pressure when operating in pressure control (kPa)."
+                }
             }
         },
-        "alarmDebounceSeconds": {
-            "default": 10,
-            "rules": {
-                "type": "number",
-                "min": 0,
-                "description": "Time a condition must persist before raising an alarm (seconds)."
+        "flowBased": {
+            "flowSetpoint": {
+                "default": 0,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Target outflow setpoint used by flow-based control (m3/h)."
+                }
+            },
+            "flowDeadband": {
+                "default": 0,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Allowed deadband around the outflow setpoint before corrective actions are taken (m3/h)."
+                }
+            },
+            "pid": {
+                "default": {},
+                "rules": {
+                    "type": "object",
+                    "schema": {
+                        "kp": {
+                            "default": 1.5,
+                            "rules": {
+                                "type": "number",
+                                "description": "Proportional gain for flow-based PID control."
+                            }
+                        },
+                        "ki": {
+                            "default": 0.05,
+                            "rules": {
+                                "type": "number",
+                                "description": "Integral gain for flow-based PID control."
+                            }
+                        },
+                        "kd": {
+                            "default": 0.01,
+                            "rules": {
+                                "type": "number",
+                                "description": "Derivative gain for flow-based PID control."
+                            }
+                        },
+                        "derivativeFilter": {
+                            "default": 0.2,
+                            "rules": {
+                                "type": "number",
+                                "min": 0,
+                                "max": 1,
+                                "description": "Derivative filter coefficient (0..1)."
+                            }
+                        },
+                        "rateUp": {
+                            "default": 30,
+                            "rules": {
+                                "type": "number",
+                                "min": 0,
+                                "description": "Maximum controller output increase rate (%/s)."
+                            }
+                        },
+                        "rateDown": {
+                            "default": 40,
+                            "rules": {
+                                "type": "number",
+                                "min": 0,
+                                "description": "Maximum controller output decrease rate (%/s)."
+                            }
+                        }
+                    }
+                }
+            },
+            "equalizationTargetPercent": {
+                "default": 60,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "max": 100,
+                    "description": "Target fill percentage of the basin when operating in equalization mode."
+                }
+            },
+            "flowBalanceTolerance": {
+                "default": 5,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Allowable error between inflow and outflow before adjustments are triggered (m3/h)."
+                }
             }
         },
-        "equalizationTargetPercent": {
-            "default": 60,
-            "rules": {
-                "type": "number",
-                "min": 0,
-                "max": 100,
-                "description": "Target fill percentage of the basin when operating in equalization mode."
+        "percentageBased": {
+            "targetVolumePercent": {
+                "default": 50,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "max": 100,
+                    "description": "Target basin volume percentage to maintain during percentage-based control."
+                }
+            },
+            "tolerancePercent": {
+                "default": 5,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Acceptable deviation from the target volume percentage before corrective action is taken."
+                }
             }
         },
-        "autoRestartAfterPowerLoss": {
-            "default": true,
-            "rules": {
-                "type": "boolean",
-                "description": "If true, pumps resume based on last known state after power restoration."
+        "powerBased": {
+            "maxPowerKW": {
+                "default": 50,
+                "rules": {
+                    "type": "number",
+                    "min": 0,
+                    "description": "Maximum allowable power consumption for the pumping station (kW)."
+                }
+            },
+            "powerControlMode": {
+                "default": "limit",
+                "rules": {
+                    "type": "enum",
+                    "values": [
+                        {
+                            "value": "limit",
+                            "description": "Limit pump operation to stay below the max power threshold."
+                        },
+                        {
+                            "value": "optimize",
+                            "description": "Optimize pump scheduling to minimize power usage while meeting flow demands."
+                        }
+                    ],
+                    "description": "Defines how power constraints are managed during operation."
+                }
             }
         },
         "manualOverrideTimeoutMinutes": {
@@ -470,13 +743,63 @@
                 "min": 0,
                 "description": "Duration after which a manual override expires automatically (minutes)."
             }
+        }
+    },
+    "safety": {
+        "enableDryRunProtection": {
+            "default": true,
+            "rules": {
+                "type": "boolean",
+                "description": "If true, pumps will be prevented from running if basin volume is too low."
+            }
         },
-        "flowBalanceTolerance": {
-            "default": 5,
+        "dryRunThresholdPercent": {
+            "default": 2,
             "rules": {
                 "type": "number",
                 "min": 0,
-                "description": "Allowable error between inflow and outflow before adjustments are triggered (m3/h)."
+                "max": 100,
+                "description": "Volume percentage below which dry run protection activates."
+            }
+        },
+        "enableOverfillProtection": {
+            "default": true,
+            "rules": {
+                "type": "boolean",
+                "description": "Deprecated alias for enableHighVolumeSafety. If true, high level alarms and shutdowns will be enforced to preserve overflow margin."
+            }
+        },
+        "enableHighVolumeSafety": {
+            "default": true,
+            "rules": {
+                "type": "boolean",
+                "description": "If true, high-volume safety actions run before the basin reaches physical overflow."
+            }
+        },
+        "overfillThresholdPercent": {
+            "default": 98,
+            "rules": {
+                "type": "number",
+                "min": 0,
+                "max": 100,
+                "description": "Deprecated alias for highVolumeSafetyThresholdPercent."
+            }
+        },
+        "highVolumeSafetyThresholdPercent": {
+            "default": 98,
+            "rules": {
+                "type": "number",
+                "min": 0,
+                "max": 100,
+                "description": "Percentage of maxVolAtOverflow where high-volume safety activates before actual overflow."
+            }
+        },
+        "timeleftToFullOrEmptyThresholdSeconds": {
+            "default": 0,
+            "rules": {
+                "type": "number",
+                "min": 0,
+                "description": "Time threshold (seconds) used to predict imminent full or empty conditions."
             }
         }
     },

src/configs/reactor.json

@@ -136,12 +136,12 @@
         }
       },
       "timeStep": {
-        "default": 0.001,
+        "default": 1,
         "rules": {
           "type": "number",
-          "min": 0.0001,
-          "unit": "h",
-          "description": "Integration time step for the reactor model."
+          "min": 0.001,
+          "unit": "s",
+          "description": "Integration time step in seconds. The kinetics engine converts to days internally (timeStep / 86400) before each ASM Euler step; the HTML editor labels this field [s] and tests assume seconds. Do not change the unit without updating baseEngine.js line 40 in the reactor submodule."
         }
       }
     },

src/configs/rotatingMachine.json

@@ -16,7 +16,7 @@
         }
       },
       "unit": {
-        "default": "m3/h",
+        "default": "l/s",
         "rules": {
           "type": "string",
           "description": "The default measurement unit for this configuration (e.g., 'meters', 'seconds', 'unitless')."
@@ -91,7 +91,56 @@
                 ],
                 "description": "Defines the position of the measurement relative to its parent equipment or system."
             }
+        },
+      "distance": {
+        "default": null,
+        "rules": {
+          "type": "number",
+          "nullable": true,
+          "description": "Optional spatial offset from the parent equipment reference. Populated from the editor when hasDistance is enabled; null otherwise."
         }
+      },
+      "distanceUnit": {
+        "default": "m",
+        "rules": {
+          "type": "string",
+          "description": "Unit for the functionality.distance offset (e.g. 'm', 'cm')."
+        }
+      },
+      "distanceDescription": {
+        "default": "",
+        "rules": {
+          "type": "string",
+          "description": "Free-text description of what the distance offset represents (e.g. 'cable length from control panel to motor')."
+        }
+      }
+    },
+    "output": {
+      "process": {
+        "default": "process",
+        "rules": {
+          "type": "enum",
+          "values": [
+            { "value": "process", "description": "Delta-compressed process message (default)." },
+            { "value": "json", "description": "Raw JSON payload." },
+            { "value": "csv", "description": "CSV-formatted payload." }
+          ],
+          "description": "Format of the process payload emitted on output port 0."
+        }
+      },
+      "dbase": {
+        "default": "influxdb",
+        "rules": {
+          "type": "enum",
+          "values": [
+            { "value": "influxdb", "description": "InfluxDB line-protocol payload (default)." },
+            { "value": "frost", "description": "FROST/SensorThings CoreSync payload." },
+            { "value": "json", "description": "Raw JSON payload." },
+            { "value": "csv", "description": "CSV-formatted payload." }
+          ],
+          "description": "Format of the telemetry payload emitted on output port 1."
+        }
+      }
     },
     "asset": {
       "uuid": {
@@ -110,6 +159,14 @@
                 "description": "Asset tag code which is a unique identifier for this asset. May be null if not assigned."
             }
         },
+      "tagNumber": {
+        "default": null,
+        "rules": {
+          "type": "string",
+          "nullable": true,
+          "description": "Optional asset tag number for legacy integrations."
+        }
+      },
       "geoLocation": {
         "default": {},
         "rules": {
@@ -140,41 +197,63 @@
           }
         }
       },
-      "supplier": {
-        "default": "Unknown",
-        "rules": {
-          "type": "string",
-          "description": "The supplier or manufacturer of the asset."
-        }
-      },
-      "category": {
-        "default": "pump",
-        "rules": {
-          "type": "string",
-          "description": "A general classification of the asset tied to the specific software. This is not chosen from the asset dropdown menu."
-        }
-      },
-      "type": {
-        "default": "Centrifugal",
-        "rules": {
-          "type": "string",
-          "description": "A more specific classification within 'type'. For example, 'centrifugal' for a centrifugal pump."
-        }
-      },
       "model": {
-        "default": "Unknown",
+        "default": null,
         "rules": {
           "type": "string",
-          "description": "A user-defined or manufacturer-defined model identifier for the asset."
+          "nullable": true,
+          "description": "Product model id (e.g. 'hidrostal-H05K-S03R'). Required at startup: the node looks the curve up via assetResolver.resolve('curves', model). Supplier/type/units are derived from the asset registry (assetResolver.resolveAssetMetadata) — do NOT save them on the node."
         }
       },
       "unit": {
-            "default": "unitless",
+            "default": null,
             "rules": {
                 "type": "string",
-                "description": "The unit of measurement for this asset (e.g., 'meters', 'seconds', 'unitless')."
+                "nullable": true,
+                "description": "Deployment unit chosen by the user (e.g. 'm3/h'). Must appear in the registry's model.units list for this model. Validated at startup."
             }
         },
+      "curveUnits": {
+        "default": {
+          "pressure": "mbar",
+          "flow": "m3/h",
+          "power": "kW",
+          "control": "%"
+        },
+        "rules": {
+          "type": "object",
+          "schema": {
+            "pressure": {
+              "default": "mbar",
+              "rules": {
+                "type": "string",
+                "description": "Pressure unit used on the machine curve dimension axis."
+              }
+            },
+            "flow": {
+              "default": "m3/h",
+              "rules": {
+                "type": "string",
+                "description": "Flow unit used in the machine curve output (nq.y)."
+              }
+            },
+            "power": {
+              "default": "kW",
+              "rules": {
+                "type": "string",
+                "description": "Power unit used in the machine curve output (np.y)."
+              }
+            },
+            "control": {
+              "default": "%",
+              "rules": {
+                "type": "string",
+                "description": "Control axis unit used in the curve x-dimension."
+              }
+            }
+          }
+        }
+      },
       "accuracy": {
         "default": null,
         "rules": {
@@ -185,43 +264,9 @@
       },
       "machineCurve": {
         "default": {
-          "nq": {
-              "1": {
-                  "x": [
-                      1,
-                      2,
-                      3,
-                      4,
-                      5
-                  ],
-                  "y": [
-                      10,
-                      20,
-                      30,
-                      40,
-                      50
-                  ]
-              }
-            },
-            "np": {
-              "1": {
-                  "x": [
-                      1,
-                      2,
-                      3,
-                      4,
-                      5
-                  ],
-                  "y": [
-                      10,
-                      20,
-                      30,
-                      40,
-                      50
-                  ]
-              }
-            }
-          },
+          "nq": {},
+          "np": {}
+        },
         "rules": {
             "type": "machineCurve",
             "description": "All machine curves must have a 'nq' and 'np' curve. nq stands for the flow curve, np stands for the power curve. Together they form the efficiency curve."
@@ -245,10 +290,6 @@
             {
               "value": "fysicalControl",
               "description": "Controlled via physical buttons or switches; ignores external automated commands."
-            },
-            {
-              "value": "maintenance",
-              "description": "No active control from auto, virtual, or fysical sources."
             }
           ],
           "description": "The operational mode of the machine."
@@ -260,7 +301,14 @@
           "type": "object",
           "schema":{
             "auto": {
-              "default": ["statusCheck", "execMovement", "execSequence", "emergencyStop"],
+              "default": [
+                "statuscheck",
+                "execmovement",
+                "execsequence",
+                "flowmovement",
+                "emergencystop",
+                "entermaintenance"
+              ],
               "rules": {
                 "type": "set",
                 "itemType": "string",
@@ -268,7 +316,14 @@
               }
             },
             "virtualControl": {
-              "default": ["statusCheck", "execMovement", "execSequence", "emergencyStop"],
+              "default": [
+                "statuscheck",
+                "execmovement",
+                "flowmovement",
+                "execsequence",
+                "emergencystop",
+                "exitmaintenance"
+              ],
               "rules": {
                 "type": "set",
                 "itemType": "string",
@@ -276,25 +331,22 @@
               }
             },
             "fysicalControl": {
-              "default": ["statusCheck", "emergencyStop"],
+              "default": [
+                "statuscheck",
+                "emergencystop",
+                "entermaintenance",
+                "exitmaintenance"
+              ],
               "rules": {
                 "type": "set",
                 "itemType": "string",
                 "description": "Actions allowed in fysicalControl mode."
               }
-            },
-            "maintenance": {
-              "default": ["statusCheck"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in maintenance mode."
-              }
+            }
             }
           },
           "description": "Information about valid command sources recognized by the machine."
-        }
-      },
+        },
       "allowedSources":{
         "default": {},
         "rules": {
@@ -386,33 +438,28 @@
               "itemType": "string",
               "description": "Sequence of states for booting up the machine."
             }
+          },
+          "entermaintenance":{
+            "default": ["stopping","coolingdown","idle","maintenance"],
+            "rules": {
+              "type": "set",
+              "itemType": "string",
+              "description": "Sequence of states if the machine is running to put it in maintenance state"
+            }
+          },
+          "exitmaintenance":{
+            "default": ["off","idle"],
+            "rules": {
+              "type": "set",
+              "itemType": "string",
+              "description": "Sequence of states if the machine is running to put it in maintenance state"
+            }
           }
         }
       },
       "description": "Predefined sequences of states for the machine."
 
     },
-    "calculationMode": {
-      "default": "medium",
-      "rules": {
-        "type": "enum",
-        "values": [
-          {
-            "value": "low",
-            "description": "Calculations run at fixed intervals (time-based)."
-          },
-          {
-            "value": "medium",
-            "description": "Calculations run when new setpoints arrive or measured changes occur (event-driven)."
-          },
-          {
-            "value": "high",
-            "description": "Calculations run on all event-driven info, including every movement."
-          }
-        ],
-        "description": "The frequency at which calculations are performed."
-      }
-    },
     "flowNumber": {
       "default": 1,
       "rules": {
@@ -422,4 +469,4 @@
       }
     }
   }
-  
+  

src/configs/valve.json

@@ -140,39 +140,20 @@
           }
         }
       },
-      "supplier": {
-        "default": "Unknown",
-        "rules": {
-          "type": "string",
-          "description": "The supplier or manufacturer of the asset."
-        }
-      },
-      "category": {
-        "default": "valve",
-        "rules": {
-          "type": "string",
-          "description": "A general classification of the asset tied to the specific software. This is not chosen from the asset dropdown menu."
-        }
-      },
-      "type": {
-        "default": "gate",
-        "rules": {
-          "type": "string",
-          "description": "A more specific classification within 'type'. For example, 'centrifugal' for a centrifugal pump."
-        }
-      },
       "model": {
-        "default": "Unknown",
+        "default": null,
         "rules": {
           "type": "string",
-          "description": "A user-defined or manufacturer-defined model identifier for the asset."
+          "nullable": true,
+          "description": "Product model id (e.g. 'binder-valve-001'). Required at startup: the node looks the curve up via assetResolver.resolve('curves', model). Supplier/type/units are derived from the asset registry (assetResolver.resolveAssetMetadata) — do NOT save them on the node."
         }
       },
       "unit": {
-            "default": "unitless",
+            "default": null,
             "rules": {
                 "type": "string",
-                "description": "The unit of measurement for this asset (e.g., 'meters', 'seconds', 'unitless')."
+                "nullable": true,
+                "description": "Deployment unit chosen by the user. Must appear in the registry's model.units list for this model. Validated at startup."
             }
         },
       "accuracy": {
@@ -224,47 +205,6 @@
           "description": "The operational mode of the machine."
         }
       },
-      "allowedActions":{
-        "default":{},
-        "rules": {
-          "type": "object",
-          "schema":{
-            "auto": {
-              "default": ["statusCheck", "execMovement", "execSequence", "emergencyStop"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in auto mode."
-              }
-            },
-            "virtualControl": {
-              "default": ["statusCheck", "execMovement", "execSequence", "emergencyStop"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in virtualControl mode."
-              }
-            },
-            "fysicalControl": {
-              "default": ["statusCheck", "emergencyStop"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in fysicalControl mode."
-              }
-            },
-            "maintenance": {
-              "default": ["statusCheck"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in maintenance mode."
-              }
-            }
-          },
-          "description": "Information about valid command sources recognized by the machine."
-        }
-      },
       "allowedSources":{
         "default": {},
         "rules": {
@@ -361,27 +301,6 @@
       },
       "description": "Predefined sequences of states for the machine."
 
-    },
-    "calculationMode": {
-      "default": "medium",
-      "rules": {
-        "type": "enum",
-        "values": [
-          {
-            "value": "low",
-            "description": "Calculations run at fixed intervals (time-based)."
-          },
-          {
-            "value": "medium",
-            "description": "Calculations run when new setpoints arrive or measured changes occur (event-driven)."
-          },
-          {
-            "value": "high",
-            "description": "Calculations run on all event-driven info, including every movement."
-          }
-        ],
-        "description": "The frequency at which calculations are performed."
-      }
     }
   }
   

src/configs/valveGroupControl.json

@@ -176,47 +176,6 @@
           "description": "The operational mode of the valveGroupControl."
         }
       },
-      "allowedActions":{
-        "default":{},
-        "rules": {
-          "type": "object",
-          "schema":{
-            "auto": {
-              "default": ["statusCheck", "execSequence", "emergencyStop", "valvePositionChange", "totalFlowChange", "valveDeltaPchange"],  
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in auto mode."
-              }
-            },
-            "virtualControl": {
-              "default": ["statusCheck", "execSequence", "emergencyStop", "valvePositionChange", "totalFlowChange", "valveDeltaPchange"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in virtualControl mode."
-              }
-            },
-            "fysicalControl": {
-              "default": ["statusCheck", "emergencyStop"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in fysicalControl mode."
-              }
-            },
-            "maintenance": {
-              "default": ["statusCheck"],
-              "rules": {
-                "type": "set",
-                "itemType": "string",
-                "description": "Actions allowed in maintenance mode."
-              }
-            }
-          },
-          "description": "Information about valid command sources recognized by the valve."
-        }
-      },
       "allowedSources":{
         "default": {},
         "rules": {
@@ -346,26 +305,5 @@
       },
       "description": "Predefined sequences of states for the valveGroupControl."
 
-    },
-    "calculationMode": {
-      "default": "medium",
-      "rules": {
-        "type": "enum",
-        "values": [
-          {
-            "value": "low",
-            "description": "Calculations run at fixed intervals (time-based)."
-          },
-          {
-            "value": "medium",
-            "description": "Calculations run when new setpoints arrive or measured changes occur (event-driven)."
-          },
-          {
-            "value": "high",
-            "description": "Calculations run on all event-driven info, including every movement."
-          }
-        ],
-        "description": "The frequency at which calculations are performed."
-      }
     }
   }

src/convert/index.js

@@ -301,4 +301,26 @@ convert = function (value) {
   return new Converter(value);
 };
 
+/**
+ * Top-level helper: list accepted unit names for a measure.
+ * Cached per measure. Unknown measures return [].
+ */
+var _possibilitiesCache = Object.create(null);
+convert.possibilities = function (measure) {
+  if (!measure || typeof measure !== 'string') return [];
+  if (_possibilitiesCache[measure]) return _possibilitiesCache[measure].slice();
+  if (!measures[measure]) {
+    _possibilitiesCache[measure] = [];
+    return [];
+  }
+  var units = Converter.prototype.possibilities.call({ origin: { measure: measure } }, measure);
+  var deduped = Array.from(new Set(units)).sort();
+  _possibilitiesCache[measure] = deduped;
+  return deduped.slice();
+};
+
+convert.measures = function () {
+  return keys(measures).slice();
+};
+
 module.exports = convert;

src/coolprop-node/src/index.js

@@ -3,11 +3,61 @@ const customRefs = require('./refData.js');
 
 class CoolPropWrapper {
     constructor() {
+
         this.initialized = false;
         this.defaultRefrigerant = null;
         this.defaultTempUnit = 'K';    // K, C, F
         this.defaultPressureUnit = 'Pa' // Pa, kPa, bar, psi
         this.customRef = false;
+        this.PropsSI = this._propsSI.bind(this);
+
+
+        // 🔹 Wastewater correction options (defaults)
+        this._ww = {
+            enabled: true,
+            tss_g_per_L: 3.5,       // default MLSS / TSS
+            density_k: 2e-4,        // +0.02% per g/L
+            viscosity_k: 0.07,      // +7% per g/L (clamped)
+            viscosity_max_gpl: 4    // cap effect at 4 g/L
+        };
+
+        this._initPromise = null;
+        this._autoInit({ refrigerant: 'Water' });
+
+    }
+
+    _isWastewaterFluid(fluidRaw) {
+        if (!fluidRaw) return false;
+        const token = String(fluidRaw).trim().toLowerCase();
+        return token === 'wastewater' || token.startsWith('wastewater:');
+    }
+
+    _parseWastewaterFluid(fluidRaw) {
+        if (!this._isWastewaterFluid(fluidRaw)) return null;
+            const ww = { ...this._ww };
+            const [, tail] = String(fluidRaw).split(':');
+            if (tail) {
+                tail.split(',').forEach(pair => {
+                    const [key, value] = pair.split('=').map(s => s.trim().toLowerCase());
+                    if (key === 'tss' && !Number.isNaN(Number(value))) {
+                        ww.tss_g_per_L = Number(value);
+                    }
+                });
+            }
+        return ww;
+    }
+
+    _applyWastewaterCorrection(outputKey, baseValue, ww) {
+        if (!Number.isFinite(baseValue) || !ww || !ww.enabled) return baseValue;
+        switch (outputKey.toUpperCase()) {
+            case 'D': // density
+                return baseValue * (1 + ww.density_k * ww.tss_g_per_L);
+            case 'V': // viscosity
+                const effTss = Math.min(ww.tss_g_per_L, ww.viscosity_max_gpl);
+                return baseValue * (1 + ww.viscosity_k * effTss);
+            default:
+                return baseValue;
+        }
     }
 
     // Temperature conversion helpers
@@ -407,13 +457,31 @@ class CoolPropWrapper {
         }
     }
 
-    // Direct access to CoolProp functions
-    async getPropsSI() {
-        if(!this.initialized) {
-            await coolprop.init();
+    _autoInit(defaults) {
+        if (!this._initPromise) {
+            this._initPromise = this.init(defaults);
         }
-        return coolprop.PropsSI;
+        return this._initPromise;
     }
+
+    _propsSI(outputKey, inKey1, inVal1, inKey2, inVal2, fluidRaw) {
+        if (!this.initialized) {
+            // Start init if no one else asked yet
+            this._autoInit({ refrigerant: this.defaultRefrigerant || 'Water' });
+            throw new Error('CoolProp is still warming up, retry PropsSI in a moment');
+        }
+        const ww = this._parseWastewaterFluid(fluidRaw);
+        const fluid = ww ? 'Water' : (this.customRefString || fluidRaw);
+        const baseValue = coolprop.PropsSI(outputKey, inKey1, inVal1, inKey2, inVal2, fluid);
+        return ww ? this._applyWastewaterCorrection(outputKey, baseValue, ww) : baseValue;
+    }
+
+    //Access to coolprop
+    async getPropsSI() {
+        await this._ensureInit({ refrigerant: this.defaultRefrigerant || 'Water' });
+        return this.PropsSI;
+    }
+    
 }
 
 module.exports = new CoolPropWrapper();

src/domain/BaseDomain.js

@@ -0,0 +1,139 @@
+/**
+ * BaseDomain — shared specificClass scaffolding.
+ *
+ * Consolidates the constructor boilerplate that every domain (pumpingStation,
+ * measurement, MGC, rotatingMachine, …) repeats today: configManager →
+ * configUtils → logger → MeasurementContainer → childRegistrationUtils →
+ * ChildRouter. Subclasses declare `static name` (matches the JSON config in
+ * generalFunctions/src/configs/<name>.json) and optionally `static unitPolicy`
+ * (a UnitPolicy.declare(...) instance), then implement `configure()` to wire
+ * concern-modules.
+ *
+ * See CONTRACTS.md §3.
+ */
+
+const EventEmitter = require('events');
+
+const configManager = require('../configs/index.js');
+const configUtils = require('../helper/configUtils.js');
+const Logger = require('../helper/logger.js');
+const childRegistrationUtils = require('../helper/childRegistrationUtils.js');
+const { MeasurementContainer } = require('../measurements/index.js');
+const ChildRouter = require('./ChildRouter.js');
+
+class BaseDomain {
+  constructor(userConfig = {}) {
+    const ctor = this.constructor;
+    if (ctor === BaseDomain) {
+      throw new Error('BaseDomain is abstract; subclass it and declare static name');
+    }
+
+    this.emitter = new EventEmitter();
+
+    this.configManager = new configManager();
+    this.defaultConfig = this.configManager.getConfig(ctor.name);
+    this.configUtils = new configUtils(this.defaultConfig);
+    this.config = this.configUtils.initConfig(userConfig);
+
+    const loggingCfg = this.config?.general?.logging || {};
+    this.logger = new Logger(
+      loggingCfg.enabled,
+      loggingCfg.logLevel,
+      this.config?.general?.name
+    );
+
+    // Read static unitPolicy via the constructor — `this.constructor`
+    // resolves to the leaf subclass even when this base ctor is the caller.
+    this.unitPolicy = ctor.unitPolicy ?? null;
+    if (this.unitPolicy && typeof this.unitPolicy.setLogger === 'function') {
+      this.unitPolicy.setLogger(this.logger);
+    }
+
+    const containerOptions = this.unitPolicy?.containerOptions
+      ? this.unitPolicy.containerOptions()
+      : { autoConvert: true };
+    this.measurements = new MeasurementContainer(containerOptions, this.logger);
+    if (this.config?.general?.id) this.measurements.setChildId(this.config.general.id);
+    if (this.config?.general?.name) this.measurements.setChildName(this.config.general.name);
+
+    this.childRegistrationUtils = new childRegistrationUtils(this);
+    this.router = new ChildRouter(this);
+
+    // childRegistrationUtils calls back into mainClass.registerChild after
+    // storing the child. Routing through `this.router` keeps subclasses free
+    // of register-switch boilerplate while preserving the existing handshake.
+    this.registerChild = (child, softwareType) => {
+      this.router.dispatchRegister(child, softwareType);
+      return true;
+    };
+
+    if (typeof this.configure === 'function') this.configure();
+    if (typeof this._init === 'function') this._init();
+  }
+
+  /**
+   * Install a read-only getter that flattens `this.child[softwareType]`
+   * (across all categories, or filtered by `category`) into a single
+   * id-keyed object. Lets subclasses expose readable accessors like
+   * `this.machines` while the registry remains the source of truth.
+   */
+  declareChildGetter(name, softwareType, category) {
+    const key = String(softwareType || '').toLowerCase();
+    Object.defineProperty(this, name, {
+      configurable: true,
+      enumerable: true,
+      get: () => {
+        const slice = this.child?.[key];
+        if (!slice) return {};
+        const cats = category ? [slice[category] || []] : Object.values(slice);
+        const out = {};
+        for (const list of cats) {
+          if (!Array.isArray(list)) continue;
+          for (const c of list) {
+            const id = c?.config?.general?.id || c?.config?.general?.name;
+            if (id != null) out[id] = c;
+          }
+        }
+        return out;
+      },
+    });
+  }
+
+  /**
+   * Frozen view passed to concern-modules so they don't reach into `this`.
+   * Subclasses may override to add domain-specific keys.
+   */
+  context() {
+    return Object.freeze({
+      config: this.config,
+      logger: this.logger,
+      measurements: this.measurements,
+      emitter: this.emitter,
+      child: this.child,
+      unitPolicy: this.unitPolicy,
+      router: this.router,
+    });
+  }
+
+  /** Default output shape — subclasses extend with concern-module snapshots. */
+  getOutput() {
+    return this.measurements.getFlattenedOutput?.() || {};
+  }
+
+  /** Subclasses MUST override. Grey placeholder so adapters never crash. */
+  getStatusBadge() {
+    return { fill: 'grey', shape: 'ring', text: 'no status' };
+  }
+
+  /** Convenience for event-driven nodes — see CONTRACTS.md §3. */
+  notifyOutputChanged() {
+    this.emitter.emit('output-changed');
+  }
+
+  close() {
+    this.router?.tearDown();
+    this.emitter.removeAllListeners();
+  }
+}
+
+module.exports = BaseDomain;

src/domain/ChildRouter.js

@@ -0,0 +1,164 @@
+/**
+ * ChildRouter — declarative parent-side child registration & event routing.
+ *
+ * Replaces the per-node `registerChild` switch + manual
+ * `child.measurements.emitter.on(...)` wiring repeated in pumpingStation,
+ * rotatingMachine and machineGroupControl.
+ *
+ * See CONTRACTS.md §5. Built on top of `childRegistrationUtils`, which
+ * already canonicalises softwareType (e.g. rotatingmachine → machine).
+ *
+ * Wildcard / partial-filter subscriptions enumerate every concrete
+ * `<type>.<variant>.<position>` event name the filter matches and attach a
+ * plain `emitter.on(...)` per combination. No emit patching — multi-parent
+ * stacks compose cleanly because each parent owns its own listeners.
+ */
+const { POSITION_VALUES } = require('../constants/positions');
+
+const SOFTWARE_TYPE_ALIASES = {
+  rotatingmachine: 'machine',
+  machinegroupcontrol: 'machinegroup',
+};
+
+// Canonical measurement-type set used to enumerate position-only and
+// match-everything filters. Sourced from MeasurementContainer.measureMap
+// plus the EVOLV-specific synthetic types the nodes routinely emit
+// (level / volumePercent / efficiency / Ncog / netFlowRate). Keep in sync
+// with MeasurementContainer if new types land there.
+const KNOWN_TYPES = Object.freeze([
+  'flow',
+  'pressure',
+  'atmPressure',
+  'power',
+  'hydraulicPower',
+  'reactivePower',
+  'apparentPower',
+  'temperature',
+  'level',
+  'volume',
+  'volumePercent',
+  'length',
+  'mass',
+  'energy',
+  'reactiveEnergy',
+  'efficiency',
+  'Ncog',
+  'netFlowRate',
+]);
+
+function canonicalType(rawType) {
+  const t = String(rawType || '').toLowerCase();
+  return SOFTWARE_TYPE_ALIASES[t] || t;
+}
+
+function lowerPosition(p) {
+  return String(p).toLowerCase();
+}
+
+class ChildRouter {
+  constructor(domain) {
+    this.domain = domain;
+    this.logger = domain?.logger || null;
+
+    this._registerSubs = new Map();      // softwareType -> Array<fn>
+    this._measurementSubs = new Map();   // softwareType -> Array<{filter, fn}>
+    this._predictionSubs = new Map();    // softwareType -> Array<{filter, fn}>
+
+    // Every plain emitter listener we attach, so tearDown can remove them.
+    this._listeners = [];
+  }
+
+  // ── declaration API ────────────────────────────────────────────────
+
+  onRegister(softwareType, fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('ChildRouter.onRegister: fn must be a function');
+    }
+    const key = canonicalType(softwareType);
+    if (!this._registerSubs.has(key)) this._registerSubs.set(key, []);
+    this._registerSubs.get(key).push(fn);
+    return this;
+  }
+
+  onMeasurement(softwareType, filter, fn) {
+    return this._addEventSub(this._measurementSubs, softwareType, filter, fn, 'onMeasurement');
+  }
+
+  onPrediction(softwareType, filter, fn) {
+    return this._addEventSub(this._predictionSubs, softwareType, filter, fn, 'onPrediction');
+  }
+
+  _addEventSub(table, softwareType, filter, fn, label) {
+    if (typeof filter === 'function' && fn === undefined) {
+      fn = filter;
+      filter = {};
+    }
+    if (typeof fn !== 'function') {
+      throw new TypeError(`ChildRouter.${label}: fn must be a function`);
+    }
+    const key = canonicalType(softwareType);
+    if (!table.has(key)) table.set(key, []);
+    table.get(key).push({ filter: filter || {}, fn });
+    return this;
+  }
+
+  // ── dispatch ──────────────────────────────────────────────────────
+
+  dispatchRegister(child, softwareType) {
+    const key = canonicalType(softwareType);
+
+    const regHandlers = this._registerSubs.get(key) || [];
+    for (const fn of regHandlers) {
+      try { fn.call(this.domain, child, key); }
+      catch (err) { this._logHandlerError('onRegister', key, err); }
+    }
+
+    const emitter = child?.measurements?.emitter;
+    if (!emitter || typeof emitter.on !== 'function') return;
+
+    this._attachVariantListeners(child, key, emitter, 'measured', this._measurementSubs);
+    this._attachVariantListeners(child, key, emitter, 'predicted', this._predictionSubs);
+  }
+
+  _attachVariantListeners(child, key, emitter, variant, table) {
+    const subs = table.get(key) || [];
+    for (const { filter, fn } of subs) {
+      const types = filter.type ? [filter.type] : KNOWN_TYPES;
+      const positions = filter.position ? [lowerPosition(filter.position)] : POSITION_VALUES.map(lowerPosition);
+      const handlerLabel = variant === 'measured' ? 'onMeasurement' : 'onPrediction';
+
+      for (const type of types) {
+        for (const pos of positions) {
+          const eventName = `${type}.${variant}.${pos}`;
+          const listener = (data) => this._invoke(fn, data, child, handlerLabel);
+          emitter.on(eventName, listener);
+          this._listeners.push({ emitter, eventName, listener });
+        }
+      }
+    }
+  }
+
+  _invoke(fn, eventData, child, handlerLabel) {
+    try { fn.call(this.domain, eventData, child); }
+    catch (err) { this._logHandlerError(handlerLabel, '', err); }
+  }
+
+  _logHandlerError(kind, key, err) {
+    if (this.logger?.warn) {
+      this.logger.warn(`ChildRouter ${kind}${key ? `[${key}]` : ''} handler threw: ${err?.message || err}`);
+    }
+  }
+
+  // ── teardown ──────────────────────────────────────────────────────
+
+  tearDown() {
+    for (const { emitter, eventName, listener } of this._listeners) {
+      if (typeof emitter.off === 'function') emitter.off(eventName, listener);
+      else if (typeof emitter.removeListener === 'function') emitter.removeListener(eventName, listener);
+    }
+    this._listeners = [];
+  }
+}
+
+module.exports = ChildRouter;
+module.exports.KNOWN_TYPES = KNOWN_TYPES;

src/domain/HealthStatus.js

@@ -0,0 +1,102 @@
+/**
+ * HealthStatus — standardised health/quality datum.
+ * Contract: see .claude/refactor/CONTRACTS.md §9.
+ *
+ * Shape (always frozen):
+ *   { level: 0|1|2|3, flags: string[], message: string, source: string|null }
+ *
+ * level 0 = nominal, 3 = unusable. Returned objects are frozen plain
+ * objects (not class instances) so they round-trip cleanly through
+ * JSON / InfluxDB serialisation.
+ */
+
+'use strict';
+
+const LABELS = ['nominal', 'minor', 'major', 'critical'];
+
+function _freeze(level, flags, message, source) {
+    return Object.freeze({
+        level,
+        flags: Object.freeze(flags.slice()),
+        message,
+        source: source == null ? null : String(source),
+    });
+}
+
+function _coerceDegradedLevel(level) {
+    const n = Math.trunc(Number(level));
+    if (!Number.isFinite(n) || n < 1) return 1;
+    if (n > 3) return 3;
+    return n;
+}
+
+function _coerceFlags(flags) {
+    if (!Array.isArray(flags)) return [];
+    const out = [];
+    for (const f of flags) {
+        if (f == null) continue;
+        out.push(String(f));
+    }
+    return out;
+}
+
+function ok(message, source) {
+    return _freeze(
+        0,
+        [],
+        typeof message === 'string' && message.length > 0 ? message : 'nominal',
+        source != null ? source : null,
+    );
+}
+
+function degraded(level, flags, message, source) {
+    const lvl = _coerceDegradedLevel(level);
+    const f = _coerceFlags(flags);
+    const m = typeof message === 'string' && message.length > 0
+        ? message
+        : LABELS[lvl];
+    return _freeze(lvl, f, m, source != null ? source : null);
+}
+
+// Merge multiple statuses into one node-level status. Worst level wins
+// for level/message/source; flags are concatenated and de-duped.
+function compose(statuses) {
+    if (!Array.isArray(statuses) || statuses.length === 0) return ok();
+
+    let worst = null;
+    const seen = new Set();
+    const flags = [];
+
+    for (const s of statuses) {
+        if (!s || typeof s !== 'object') continue;
+        const lvl = Number.isFinite(s.level) ? s.level : 0;
+        if (worst === null || lvl > worst.level) {
+            worst = { level: lvl, message: s.message, source: s.source ?? null };
+        }
+        if (Array.isArray(s.flags)) {
+            for (const f of s.flags) {
+                if (f == null) continue;
+                const k = String(f);
+                if (!seen.has(k)) {
+                    seen.add(k);
+                    flags.push(k);
+                }
+            }
+        }
+    }
+
+    if (worst === null) return ok();
+
+    const message = typeof worst.message === 'string' && worst.message.length > 0
+        ? worst.message
+        : LABELS[Math.max(0, Math.min(3, worst.level))];
+    return _freeze(worst.level, flags, message, worst.source);
+}
+
+function label(level) {
+    const n = Math.trunc(Number(level));
+    if (!Number.isFinite(n) || n < 0 || n > 3) return 'unknown';
+    return LABELS[n];
+}
+
+module.exports = { ok, degraded, compose, label };

src/domain/LatestWinsGate.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// Serialises an async dispatch so that high-frequency callers cannot stack
+// up overlapping invocations. Intermediate values are dropped — only the
+// most recent fire()/fireAndWait() during an in-flight dispatch is replayed
+// afterwards. Extracted from machineGroupControl's _dispatchInFlight +
+// _delayedCall pattern so MGC, pumpingStation, valveGroupControl etc. can
+// share it.
+//
+// fire(value)        — never blocks; returns void.
+// fireAndWait(value) — returns a promise that settles when THIS value's
+//                      dispatch runs to completion. If a later fireAndWait
+//                      arrives during the in-flight call and supersedes
+//                      this one in the pending slot, the returned promise
+//                      RESOLVES with { superseded: true } instead of
+//                      rejecting — callers can branch on a sentinel
+//                      without try/catch. The dispatch's own return value
+//                      (when not superseded) is forwarded as the resolution.
+
+const SUPERSEDED = Object.freeze({ superseded: true });
+
+class LatestWinsGate {
+    constructor(asyncDispatchFn, options = {}) {
+        if (typeof asyncDispatchFn !== 'function') {
+            throw new TypeError('LatestWinsGate requires an async dispatch function');
+        }
+        this._dispatch = asyncDispatchFn;
+        this._logger = options.logger || null;
+        this._inFlight = false;
+        this._pending = null;          // { value, ctx, settle? } | null
+        this._drainResolvers = [];     // resolved when idle again
+        this.lastError = null;
+    }
+
+    // 0 = idle, 1 = running with no pending, 2 = running with pending.
+    get size() {
+        if (!this._inFlight) return 0;
+        return this._pending ? 2 : 1;
+    }
+
+    // Never blocks. If a dispatch is in flight, the latest value is parked;
+    // older parked values are silently overwritten.
+    fire(value, ctx) {
+        if (this._inFlight) {
+            this._supersedePending();
+            this._pending = { value, ctx, settle: null };
+            return;
+        }
+        this._run(value, ctx, null);
+    }
+
+    // Returns a promise that resolves when THIS fire's dispatch settles.
+    // If this fire gets overwritten while parked, resolves with the
+    // SUPERSEDED sentinel ({ superseded: true }) — callers branch on
+    // result.superseded === true without try/catch.
+    fireAndWait(value, ctx) {
+        return new Promise((resolve) => {
+            const settle = resolve;
+            if (this._inFlight) {
+                this._supersedePending();
+                this._pending = { value, ctx, settle };
+                return;
+            }
+            this._run(value, ctx, settle);
+        });
+    }
+
+    drain() {
+        if (!this._inFlight && !this._pending) return Promise.resolve();
+        return new Promise((resolve) => { this._drainResolvers.push(resolve); });
+    }
+
+    _supersedePending() {
+        const prev = this._pending;
+        if (prev && typeof prev.settle === 'function') prev.settle(SUPERSEDED);
+        this._pending = null;
+    }
+
+    _run(value, ctx, settle) {
+        this._inFlight = true;
+        // Kick the dispatch on a microtask so fire()/fireAndWait() always
+        // return synchronously, even if _dispatch resolves immediately.
+        Promise.resolve()
+            .then(() => this._dispatch(value, ctx))
+            .then((result) => {
+                if (typeof settle === 'function') settle(result);
+            }, (err) => {
+                this.lastError = err;
+                if (this._logger && typeof this._logger.error === 'function') {
+                    this._logger.error(err);
+                }
+                // Resolve (not reject) so fireAndWait callers don't need
+                // try/catch. Dispatch errors stay observable via lastError.
+                if (typeof settle === 'function') settle(undefined);
+            })
+            .then(() => this._afterDispatch());
+    }
+
+    _afterDispatch() {
+        this._inFlight = false;
+        if (this._pending) {
+            const { value, ctx, settle } = this._pending;
+            this._pending = null;
+            this._run(value, ctx, settle);
+            return;
+        }
+        // Idle — release any drain() waiters.
+        const waiters = this._drainResolvers;
+        this._drainResolvers = [];
+        for (const r of waiters) r();
+    }
+}
+
+LatestWinsGate.SUPERSEDED = SUPERSEDED;
+
+module.exports = LatestWinsGate;

src/domain/UnitPolicy.js

@@ -0,0 +1,163 @@
+const convert = require('../convert/index.js');
+
+// Map MeasurementContainer measurement-type names to convert-module
+// "measure" families. Mirrors MeasurementContainer.measureMap so a policy
+// declared with the type names domains use ('flow', 'pressure', ...) can be
+// validated against the same convert-module families MeasurementContainer
+// uses internally.
+const TYPE_TO_MEASURE = Object.freeze({
+  pressure: 'pressure',
+  atmpressure: 'pressure',
+  flow: 'volumeFlowRate',
+  power: 'power',
+  hydraulicpower: 'power',
+  reactivepower: 'reactivePower',
+  apparentpower: 'apparentPower',
+  temperature: 'temperature',
+  volume: 'volume',
+  length: 'length',
+  mass: 'mass',
+  energy: 'energy',
+  reactiveenergy: 'reactiveEnergy',
+});
+
+const DEFAULT_REQUIRED_TYPES = Object.freeze(['flow', 'pressure', 'power', 'temperature']);
+
+class UnitPolicy {
+  constructor({ canonical, output, curve, requireUnitForTypes, logger } = {}) {
+    this._canonical = freezeShallow(canonical);
+    this._output = freezeShallow(output);
+    this._curve = curve ? freezeShallow(curve) : null;
+    this._requireUnitForTypes = Object.freeze(
+      Array.isArray(requireUnitForTypes) ? [...requireUnitForTypes] : [...DEFAULT_REQUIRED_TYPES]
+    );
+    this._logger = logger || null;
+    // Warn-once memo: same (label, candidate) pair only logs the first time.
+    this._warned = new Set();
+
+    // Dual-shape accessors: each of canonical/output/curve is BOTH a method
+    // (legacy `policy.canonical('flow')`) AND a frozen property bag
+    // (`policy.canonical.flow`). The function carries the frozen map's own
+    // properties via Object.defineProperty so consumers can pick either form.
+    this.canonical = makeAccessor(this._canonical);
+    this.output = makeAccessor(this._output);
+    this.curve = makeAccessor(this._curve || {});
+  }
+
+  static declare(spec = {}) {
+    if (!spec.canonical || typeof spec.canonical !== 'object') {
+      throw new Error('UnitPolicy.declare: canonical units map is required');
+    }
+    if (!spec.output || typeof spec.output !== 'object') {
+      throw new Error('UnitPolicy.declare: output units map is required');
+    }
+    return new UnitPolicy(spec);
+  }
+
+  setLogger(logger) {
+    this._logger = logger || null;
+    return this;
+  }
+
+  /**
+   * Validate a user-supplied unit string against `expectedMeasure`. On any
+   * mismatch return `fallback` and warn once for this (label, candidate)
+   * pair. On success return the trimmed candidate.
+   */
+  resolve(candidate, expectedMeasure, fallback, label = 'unit') {
+    const fallbackUnit = String(fallback || '').trim();
+    const raw = typeof candidate === 'string' ? candidate.trim() : '';
+    if (!raw) return fallbackUnit;
+
+    try {
+      const desc = convert().describe(raw);
+      const measure = resolveMeasure(expectedMeasure);
+      if (measure && desc.measure !== measure) {
+        throw new Error(`expected ${measure} but got ${desc.measure}`);
+      }
+      return raw;
+    } catch (error) {
+      this._warnOnce(label, raw, `Invalid ${label} unit '${raw}' (${error.message}). Falling back to '${fallbackUnit}'.`);
+      return fallbackUnit;
+    }
+  }
+
+  /**
+   * Strict numeric conversion. Throws if value is not finite.
+   * No-ops (still returning a Number) when from/to are missing or equal.
+   */
+  convert(value, fromUnit, toUnit, contextLabel = 'unit conversion') {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric)) {
+      throw new Error(`${contextLabel}: value '${value}' is not finite`);
+    }
+    if (!fromUnit || !toUnit || fromUnit === toUnit) return numeric;
+    return convert(numeric).from(fromUnit).to(toUnit);
+  }
+
+  /**
+   * Returns the option bag for `new MeasurementContainer(options, logger)`.
+   * Exact shape required by MeasurementContainer; see
+   * src/measurements/MeasurementContainer.js constructor.
+   */
+  containerOptions() {
+    const defaultUnits = { ...this._output };
+    const preferredUnits = { ...this._output };
+    const canonicalUnits = { ...this._canonical };
+    return {
+      defaultUnits,
+      preferredUnits,
+      canonicalUnits,
+      storeCanonical: true,
+      strictUnitValidation: true,
+      throwOnInvalidUnit: true,
+      requireUnitForTypes: [...this._requireUnitForTypes],
+    };
+  }
+
+  _warnOnce(label, candidate, message) {
+    const key = `${label}::${candidate}`;
+    if (this._warned.has(key)) return;
+    this._warned.add(key);
+    if (this._logger && typeof this._logger.warn === 'function') {
+      this._logger.warn(message);
+    } else {
+      // Last-resort fallback so misconfigurations don't go silent in
+      // domains that haven't wired a logger yet.
+      console.warn(message);
+    }
+  }
+}
+
+function freezeShallow(obj) {
+  return Object.freeze({ ...(obj || {}) });
+}
+
+// Build a function that doubles as a frozen property bag. `accessor(type)`
+// returns the unit for that type (legacy method shape). `accessor.flow` etc.
+// return the unit directly (new property shape). Own-properties are
+// non-writable, non-configurable; attempts to assign / delete / redefine
+// throw in strict mode — proving the bag is genuinely frozen.
+function makeAccessor(map) {
+  const fn = (type) => map[type] || null;
+  for (const key of Object.keys(map)) {
+    Object.defineProperty(fn, key, {
+      value: map[key],
+      writable: false,
+      enumerable: true,
+      configurable: false,
+    });
+  }
+  return Object.freeze(fn);
+}
+
+// Accepts either the convert-module measure family ('volumeFlowRate') or one
+// of our type names ('flow') and returns the convert-module measure.
+function resolveMeasure(expected) {
+  if (!expected) return null;
+  const lower = String(expected).trim().toLowerCase();
+  if (TYPE_TO_MEASURE[lower]) return TYPE_TO_MEASURE[lower];
+  return expected;
+}
+
+module.exports = UnitPolicy;

src/helper/assertionUtils.js

@@ -26,4 +26,4 @@ class Assertions {
     }
 }
 
-module.exports = Assertions;
+module.exports = Assertions;

src/helper/assetUtils.js

@@ -1,5 +1,244 @@
-function getAssetVariables() {
+const http = require('node:http');
+const https = require('node:https');
+const { URL } = require('node:url');
+const { assetCategoryManager } = require('../../datasets/assetData');
 
+function toNumber(value, fallback = 1) {
+  const result = Number(value);
+  return Number.isFinite(result) && result > 0 ? result : fallback;
 }
 
-module.exports = { getAssetVariables };
+function toArray(value = []) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => typeof item !== 'undefined' && item !== null);
+  }
+  if (typeof value === 'string' && value.trim()) {
+    return [value.trim()];
+  }
+  if (typeof value === 'number') {
+    return [value];
+  }
+  return [];
+}
+
+function findModelMetadata(selection = {}) {
+  if (!selection) {
+    return null;
+  }
+
+  const categoryKey = selection.softwareType || 'measurement';
+  if (!assetCategoryManager.hasCategory(categoryKey)) {
+    return null;
+  }
+
+  const suppliers = assetCategoryManager.getCategory(categoryKey).suppliers || [];
+  const supplierMatch = (entry, value) => {
+    if (!entry || !value) return false;
+    const key = value.toString().toLowerCase();
+    return (
+      (entry.id && entry.id.toLowerCase() === key) ||
+      (entry.name && entry.name.toLowerCase() === key)
+    );
+  };
+
+  const supplier = suppliers.find((item) => supplierMatch(item, selection.supplier));
+  const types = supplier?.types || [];
+  const type = types.find((item) => supplierMatch(item, selection.assetType));
+  const models = type?.models || [];
+  const model = models.find((item) => supplierMatch(item, selection.model));
+
+  return model || null;
+}
+
+function buildAssetPayload({ assetSelection = {}, registrationDefaults = {} }) {
+  const defaults = {
+    profileId: 1,
+    locationId: 1,
+    processId: 1,
+    status: 'actief',
+    childAssets: [],
+    ...registrationDefaults
+  };
+
+  const metadata = assetSelection.modelMetadata || findModelMetadata(assetSelection) || {};
+  const rawName = assetSelection.assetName || assetSelection.name || assetSelection.assetType || assetSelection.model;
+  const assetName = (rawName || 'Measurement asset').toString();
+  const assetDescription = (assetSelection.assetDescription || assetSelection.description || assetName).toString();
+
+  const modelId = metadata.product_model_id ?? metadata.id ?? assetSelection.modelId ?? assetSelection.model ?? null;
+
+  const payload = {
+    profile_id: toNumber(defaults.profileId, 1),
+    location_id: toNumber(defaults.locationId, 1),
+    process_id: toNumber(defaults.processId, 1),
+    asset_name: assetName,
+    asset_description: assetDescription,
+    asset_status: (assetSelection.assetStatus || defaults.status || 'actief').toString(),
+    product_model_id: modelId,
+    product_model_uuid: metadata.product_model_uuid || metadata.uuid || null,
+    child_assets: toArray(defaults.childAssets)
+  };
+
+  const validation = [];
+  const missing = [];
+  const tooLong = [];
+  const invalid = [];
+
+  if (!payload.asset_name) {
+    missing.push('asset_name');
+  } else if (payload.asset_name.length > 100) {
+    tooLong.push('asset_name');
+  }
+
+  if (!payload.asset_status) {
+    missing.push('asset_status');
+  } else if (payload.asset_status.length > 20) {
+    tooLong.push('asset_status');
+  }
+
+  if (!Number.isInteger(payload.location_id)) {
+    invalid.push('location_id');
+  }
+  if (!Number.isInteger(payload.process_id)) {
+    invalid.push('process_id');
+  }
+  if (!Number.isInteger(payload.profile_id)) {
+    invalid.push('profile_id');
+  }
+
+  if (!Number.isInteger(payload.product_model_id)) {
+    invalid.push('product_model_id');
+  }
+
+  if (!Array.isArray(payload.child_assets)) {
+    invalid.push('child_assets');
+  }
+
+  if (missing.length) {
+    validation.push(`missing: ${missing.join(', ')}`);
+  }
+  if (tooLong.length) {
+    validation.push(`too long: ${tooLong.join(', ')}`);
+  }
+  if (invalid.length) {
+    validation.push(`invalid type: ${invalid.join(', ')}`);
+  }
+
+  if (validation.length) {
+    console.warn('[assetUtils] payload validation', validation.join(' | '));
+  } else {
+    console.info('[assetUtils] payload validation ok');
+  }
+
+  const tagNumber = typeof assetSelection.tagNumber === 'string' && assetSelection.tagNumber.trim()
+    ? assetSelection.tagNumber.trim()
+    : null;
+
+  return {
+    payload,
+    tagNumber,
+    isUpdate: Boolean(tagNumber)
+  };
+}
+
+function normalizeHeaders(headers = {}, body = '') {
+  const normalized = { ...headers };
+  if (!Object.prototype.hasOwnProperty.call(normalized, 'Content-Length')) {
+    normalized['Content-Length'] = Buffer.byteLength(body);
+  }
+  return normalized;
+}
+
+function prepareUrl(baseUrl = '', path = '') {
+  const trimmedBase = (baseUrl || '').replace(/\/+$/g, '').replace(/\\/g, '/');
+  const trimmedPath = path.startsWith('/') ? path : `/${path}`;
+  if (!trimmedBase) {
+    return trimmedPath;
+  }
+  return `${trimmedBase}${trimmedPath}`;
+}
+
+function sendHttpRequest(url, method, headers = {}, body = '') {
+  const parsedUrl = new URL(url, 'http://localhost');
+  const agent = parsedUrl.protocol === 'https:' ? https : http;
+  const requestOptions = {
+    method,
+    hostname: parsedUrl.hostname,
+    port: parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
+    path: `${parsedUrl.pathname}${parsedUrl.search}`,
+    headers: normalizeHeaders(headers, body)
+  };
+
+  return new Promise((resolve, reject) => {
+    const req = agent.request(requestOptions, (res) => {
+      let raw = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { raw += chunk; });
+      res.on('end', () => resolve({ status: res.statusCode, body: raw }));
+    });
+
+    req.on('error', reject);
+    if (body) {
+      req.write(body);
+    }
+    req.end();
+  });
+}
+
+function parseApiResponse(raw, status) {
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      success: parsed.success === true,
+      data: parsed.data || null,
+      message: parsed.message || (status >= 400 ? `HTTP ${status}` : 'Result returned')
+    };
+  } catch (error) {
+    return {
+      success: false,
+      data: raw,
+      message: `Unable to decode asset API response: ${error.message}`
+    };
+  }
+}
+
+async function syncAsset({ assetSelection = {}, registrationDefaults = {}, apiConfig = {}, nodeContext = {} }) {
+  const { payload, tagNumber, isUpdate } = buildAssetPayload({ assetSelection, registrationDefaults });
+  if (!apiConfig || !apiConfig.baseUrl) {
+    const message = 'Asset API configuration is missing';
+    console.warn('[assetUtils] ' + message, { nodeContext });
+    return { success: false, data: null, message };
+  }
+
+  const path = isUpdate && tagNumber && typeof apiConfig.updatePath === 'function'
+    ? apiConfig.updatePath(tagNumber)
+    : apiConfig.registerPath;
+  const url = prepareUrl(apiConfig.baseUrl, path);
+  const method = isUpdate ? (apiConfig.updateMethod || 'PUT') : 'POST';
+  const headers = apiConfig.headers || {};
+
+  console.info('[assetUtils] Sending asset update', { nodeContext, method, url });
+
+  try {
+    const response = await sendHttpRequest(url, method, headers, JSON.stringify(payload));
+    const parsed = parseApiResponse(response.body, response.status);
+    return {
+      success: parsed.success,
+      data: parsed.data,
+      message: parsed.message
+    };
+  } catch (error) {
+    console.error('[assetUtils] Asset API request failed', error, { nodeContext });
+    return {
+      success: false,
+      data: null,
+      message: `Asset API request error: ${error.message}`
+    };
+  }
+}
+
+module.exports = {
+  syncAsset,
+  buildAssetPayload,
+  findModelMetadata
+};

src/helper/childRegistrationUtils.js

@@ -1,3 +1,17 @@
+// Map a child's raw softwareType (the lowercased node name from
+// buildConfig) to the "role" key that parent registerChild() handlers
+// dispatch on. Without this, MGC/pumpingStation register-handlers (which
+// branch on 'machine' / 'machinegroup' / 'pumpingstation' / 'measurement')
+// silently miss every real production child because rotatingMachine
+// reports softwareType='rotatingmachine' and machineGroupControl reports
+// 'machinegroupcontrol'. Existing tests that pass already-aliased keys
+// ('machine', 'machinegroup') stay green because those aren't in the
+// alias map and pass through unchanged.
+const SOFTWARE_TYPE_ALIASES = {
+  rotatingmachine: 'machine',
+  machinegroupcontrol: 'machinegroup',
+};
+
 class ChildRegistrationUtils {
   constructor(mainClass) {
     this.mainClass = mainClass;
@@ -5,9 +19,20 @@ class ChildRegistrationUtils {
     this.registeredChildren = new Map();
   }
 
-  async registerChild(child, positionVsParent, _distance) {
-    const softwareType = (child.config.functionality.softwareType || '').toLowerCase();
-    const { name, id } = child.config.general;
+  async registerChild(child, positionVsParent, distance) {
+    if (!child || typeof child !== 'object') {
+      this.logger?.warn('registerChild skipped: invalid child payload');
+      return false;
+    }
+    if (!child.config?.functionality || !child.config?.general) {
+      this.logger?.warn('registerChild skipped: missing child config/functionality/general');
+      return false;
+    }
+
+    const rawSoftwareType = (child.config.functionality.softwareType || '').toLowerCase();
+    const softwareType = SOFTWARE_TYPE_ALIASES[rawSoftwareType] || rawSoftwareType;
+    const name = child.config.general.name || child.config.general.id || 'unknown';
+    const id = child.config.general.id || name;
 
     this.logger.debug(`Registering child: ${name} (${id}) as ${softwareType} at ${positionVsParent}`);
 
@@ -43,19 +68,21 @@ class ChildRegistrationUtils {
     }
 
     this.logger.info(`✅ Child ${name} registered successfully`);
+    return true;
   }
 
   _storeChild(child, softwareType) {
     // Maintain your existing structure
     if (!this.mainClass.child) this.mainClass.child = {};
-    if (!this.mainClass.child[softwareType]) this.mainClass.child[softwareType] = {};
+    const typeKey = softwareType || 'unknown';
+    if (!this.mainClass.child[typeKey]) this.mainClass.child[typeKey] = {};
     
     const { category = "sensor" } = child.config.asset || {};
-    if (!this.mainClass.child[softwareType][category]) {
-      this.mainClass.child[softwareType][category] = [];
+    if (!this.mainClass.child[typeKey][category]) {
+      this.mainClass.child[typeKey][category] = [];
     }
     
-    this.mainClass.child[softwareType][category].push(child);
+    this.mainClass.child[typeKey][category].push(child);
   }
 
   // NEW: Utility methods for parent to use
@@ -95,4 +122,4 @@ class ChildRegistrationUtils {
   }
 }
 
-module.exports = ChildRegistrationUtils;
+module.exports = ChildRegistrationUtils;

src/helper/configUtils.js

@@ -39,8 +39,8 @@ const Logger = require("./logger");
 
 class ConfigUtils {
     constructor(defaultConfig, IloggerEnabled , IloggerLevel) {
-        const loggerEnabled = IloggerEnabled || true;
-        const loggerLevel = IloggerLevel || "warn";
+        const loggerEnabled = IloggerEnabled ?? true;
+        const loggerLevel = IloggerLevel ?? "warn";
         this.logger = new Logger(loggerEnabled, loggerLevel, 'ConfigUtils');
         this.defaultConfig = defaultConfig;
         this.validationUtils = new ValidationUtils(loggerEnabled, loggerLevel);
@@ -73,17 +73,25 @@ class ConfigUtils {
         return updatedConfig;
     }
 
+    _isPlainObject(value) {
+        return Object.prototype.toString.call(value) === '[object Object]';
+    }
+
     // loop through objects and merge them obj1 will be updated with obj2 values
     mergeObjects(obj1, obj2) {
         for (let key in obj2) {
             if (Object.prototype.hasOwnProperty.call(obj2, key)) {
-                if (typeof obj2[key] === 'object') {
-                    if (!obj1[key]) {
+                const nextValue = obj2[key];
+
+                if (Array.isArray(nextValue)) {
+                    obj1[key] = [...nextValue];
+                } else if (this._isPlainObject(nextValue)) {
+                    if (!this._isPlainObject(obj1[key])) {
                         obj1[key] = {};
                     }
-                    this.mergeObjects(obj1[key], obj2[key]);
+                    this.mergeObjects(obj1[key], nextValue);
                 } else {
-                    obj1[key] = obj2[key];
+                    obj1[key] = nextValue;
                 }
             }
         }

src/helper/endpointUtils.js

@@ -18,13 +18,102 @@ class EndpointUtils {
    * @param {string} nodeName     the name of the node (used in the URL)
    * @param {object} customHelpers  additional helper functions to inject
    */
-  createMenuUtilsEndpoint(RED, nodeName, customHelpers = {}) {
-    RED.httpAdmin.get(`/${nodeName}/resources/menuUtils.js`, (req, res) => {
-      console.log(`Serving menuUtils.js for ${nodeName} node`);
-      res.set('Content-Type', 'application/javascript');
-      const browserCode = this.generateMenuUtilsCode(nodeName, customHelpers);
-      res.send(browserCode);
+  createMenuUtilsEndpoint(RED, nodeName, customHelpers = {}, options = {}) {
+    const basePath = `/${nodeName}/resources`;
+
+    RED.httpAdmin.get(`${basePath}/menuUtilsData.json`, (req, res) => {
+      res.json(this.generateMenuUtilsData(nodeName, customHelpers, options));
     });
+
+    RED.httpAdmin.get(`${basePath}/menuUtils.legacy.js`, (req, res) => {
+      res.set('Content-Type', 'application/javascript');
+      res.send(this.generateLegacyMenuUtilsCode(nodeName, customHelpers));
+    });
+
+    RED.httpAdmin.get(`${basePath}/menuUtils.js`, (req, res) => {
+      res.set('Content-Type', 'application/javascript');
+      res.send(this.generateMenuUtilsBootstrap(nodeName));
+    });
+  }
+
+  generateMenuUtilsData(nodeName, customHelpers = {}, options = {}) {
+    const defaultHelpers = {
+      validateRequired: `function(value) {
+        return value != null && value.toString().trim() !== '';
+      }`,
+      formatDisplayValue: `function(value, unit) {
+        return \`${'${'}value} ${'${'}unit || ''}\`.trim();
+      }`,
+      validateScaling: `function(min, max) {
+        return !isNaN(min) && !isNaN(max) && Number(min) < Number(max);
+      }`,
+      validateUnit: `function(unit) {
+        return typeof unit === 'string' && unit.trim() !== '';
+      }`,
+    };
+
+    return {
+      nodeName,
+      helpers: { ...defaultHelpers, ...customHelpers },
+      options: {
+        autoLoadLegacy: options.autoLoadLegacy !== false,
+      },
+    };
+  }
+
+  generateMenuUtilsBootstrap(nodeName) {
+    return `
+// Stable bootstrap for EVOLV menu utils (${nodeName})
+(function() {
+  const nodeName = ${JSON.stringify(nodeName)};
+  const basePath = '/' + nodeName + '/resources';
+
+  window.EVOLV = window.EVOLV || {};
+  window.EVOLV.nodes = window.EVOLV.nodes || {};
+  window.EVOLV.nodes[nodeName] = window.EVOLV.nodes[nodeName] || {};
+  window.EVOLV.nodes[nodeName].utils = window.EVOLV.nodes[nodeName].utils || {};
+
+  function parseHelper(fnBody) {
+    try {
+      return (new Function('return (' + fnBody + ')'))();
+    } catch (error) {
+      console.error('[menuUtils] helper parse failed:', error);
+      return function() { return null; };
+    }
+  }
+
+  function loadLegacyIfNeeded(autoLoadLegacy) {
+    if (!autoLoadLegacy || typeof window.MenuUtils === 'function') return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const script = document.createElement('script');
+      script.src = basePath + '/menuUtils.legacy.js';
+      script.onload = resolve;
+      script.onerror = reject;
+      document.head.appendChild(script);
+    });
+  }
+
+  fetch(basePath + '/menuUtilsData.json')
+    .then(function(res) { return res.json(); })
+    .then(function(payload) {
+      const helperFns = {};
+      Object.entries(payload.helpers || {}).forEach(function(entry) {
+        helperFns[entry[0]] = parseHelper(entry[1]);
+      });
+
+      window.EVOLV.nodes[nodeName].utils.helpers = helperFns;
+      return loadLegacyIfNeeded(payload.options && payload.options.autoLoadLegacy);
+    })
+    .then(function() {
+      if (typeof window.MenuUtils === 'function' && !window.EVOLV.nodes[nodeName].utils.menuUtils) {
+        window.EVOLV.nodes[nodeName].utils.menuUtils = new window.MenuUtils();
+      }
+    })
+    .catch(function(error) {
+      console.error('[menuUtils] bootstrap failed for ' + nodeName, error);
+    });
+})();
+`;
   }
 
   /**
@@ -33,7 +122,7 @@ class EndpointUtils {
    * @param {object} customHelpers  map of name: functionString pairs
    * @returns {string}  a JS snippet to run in the browser
    */
-  generateMenuUtilsCode(nodeName, customHelpers = {}) {
+  generateLegacyMenuUtilsCode(nodeName, customHelpers = {}) {
     // Default helper implementations to expose alongside MenuUtils
     const defaultHelpers = {
       validateRequired: `function(value) {
@@ -101,6 +190,11 @@ ${helpersCode}
 console.log('Loaded EVOLV.nodes.${nodeName}.utils.menuUtils');
 `;
   }
+
+  // Backward-compatible alias.
+  generateMenuUtilsCode(nodeName, customHelpers = {}) {
+    return this.generateLegacyMenuUtilsCode(nodeName, customHelpers);
+  }
 }
 
 module.exports = EndpointUtils;

src/helper/formatters/csvFormatter.js

@@ -0,0 +1,44 @@
+/**
+ * CSV formatter
+ * Produces a single CSV line: timestamp,measurement,field1=val1,field2=val2,...
+ *
+ * Values are escaped if they contain commas or quotes.
+ *
+ * @param {string} measurement - The measurement name (e.g. node name)
+ * @param {object} metadata    - { fields, tags }
+ *   - fields: key/value pairs of changed data points
+ *   - tags:   flat key/value string pairs (included as columns)
+ * @returns {string} CSV-formatted line
+ */
+function format(measurement, metadata) {
+  const { fields, tags } = metadata;
+  const timestamp = new Date().toISOString();
+  const parts = [escapeCSV(timestamp), escapeCSV(measurement)];
+
+  // Append tags first, then fields
+  if (tags) {
+    for (const key of Object.keys(tags).sort()) {
+      parts.push(escapeCSV(`${key}=${tags[key]}`));
+    }
+  }
+
+  for (const key of Object.keys(fields).sort()) {
+    parts.push(escapeCSV(`${key}=${fields[key]}`));
+  }
+
+  return parts.join(',');
+}
+
+/**
+ * Escapes a value for safe inclusion in a CSV field.
+ * Wraps in double quotes if the value contains a comma, quote, or newline.
+ */
+function escapeCSV(value) {
+  const str = String(value);
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return '"' + str.replace(/"/g, '""') + '"';
+  }
+  return str;
+}
+
+module.exports = { format };

src/helper/formatters/frostFormatter.js

@@ -0,0 +1,23 @@
+/**
+ * FROST handoff formatter
+ * -----------------------
+ * Keeps the same structured envelope as the InfluxDB formatter so a shared
+ * CoreSync collector can accept existing EVOLV dbase messages without coupling
+ * producing nodes to FROST HTTP details.
+ */
+function format(measurement, metadata) {
+  const { fields, tags, config } = metadata;
+  return {
+    measurement,
+    fields,
+    tags: tags || {},
+    timestamp: new Date().toISOString(),
+    source: {
+      nodeId: config?.general?.id,
+      softwareType: config?.functionality?.softwareType,
+      unit: config?.general?.unit || config?.asset?.unit,
+    },
+  };
+}
+
+module.exports = { format };

src/helper/formatters/index.js

@@ -0,0 +1,62 @@
+/**
+ * Formatter Registry
+ * ------------------
+ * Maps format names to formatter modules.
+ * Each formatter exports: format(measurement, metadata) => string|object
+ *
+ * Usage:
+ *   const { getFormatter, registerFormatter } = require('./formatters');
+ *   const fmt = getFormatter('json');
+ *   const output = fmt.format('pump1', { fields: {...}, tags: {...} });
+ */
+
+const influxdbFormatter = require('./influxdbFormatter');
+const jsonFormatter = require('./jsonFormatter');
+const csvFormatter = require('./csvFormatter');
+const processFormatter = require('./processFormatter');
+const frostFormatter = require('./frostFormatter');
+
+// Built-in registry
+const registry = {
+  influxdb: influxdbFormatter,
+  json: jsonFormatter,
+  csv: csvFormatter,
+  process: processFormatter,
+  frost: frostFormatter,
+};
+
+/**
+ * Retrieve a formatter by name.
+ * @param {string} name - Format name (e.g. 'influxdb', 'json', 'csv')
+ * @returns {object} Formatter with a .format() method
+ * @throws {Error} If the format name is not registered
+ */
+function getFormatter(name) {
+  const formatter = registry[name];
+  if (!formatter) {
+    throw new Error(`Unknown output format: "${name}". Registered formats: ${Object.keys(registry).join(', ')}`);
+  }
+  return formatter;
+}
+
+/**
+ * Register a custom formatter at runtime.
+ * @param {string} name      - Format name
+ * @param {object} formatter - Object with a .format(measurement, metadata) method
+ */
+function registerFormatter(name, formatter) {
+  if (typeof formatter.format !== 'function') {
+    throw new Error('Formatter must have a .format(measurement, metadata) method');
+  }
+  registry[name] = formatter;
+}
+
+/**
+ * List all registered format names.
+ * @returns {string[]}
+ */
+function getRegisteredFormats() {
+  return Object.keys(registry);
+}
+
+module.exports = { getFormatter, registerFormatter, getRegisteredFormats };

src/helper/formatters/influxdbFormatter.js

@@ -0,0 +1,22 @@
+/**
+ * InfluxDB formatter
+ * Produces the structured object expected by Node-RED InfluxDB nodes:
+ *   { measurement, fields, tags, timestamp }
+ *
+ * @param {string} measurement - The measurement name (e.g. node name)
+ * @param {object} metadata    - { fields, tags }
+ *   - fields: key/value pairs of changed data points
+ *   - tags:   flat key/value string pairs (InfluxDB tags)
+ * @returns {string|object} Formatted payload (object for InfluxDB)
+ */
+function format(measurement, metadata) {
+  const { fields, tags } = metadata;
+  return {
+    measurement: measurement,
+    fields: fields,
+    tags: tags || {},
+    timestamp: new Date(),
+  };
+}
+
+module.exports = { format };

src/helper/formatters/jsonFormatter.js

@@ -0,0 +1,22 @@
+/**
+ * JSON formatter
+ * Produces a JSON string suitable for MQTT, REST APIs, etc.
+ *
+ * @param {string} measurement - The measurement name (e.g. node name)
+ * @param {object} metadata    - { fields, tags }
+ *   - fields: key/value pairs of changed data points
+ *   - tags:   flat key/value string pairs
+ * @returns {string} JSON-encoded string
+ */
+function format(measurement, metadata) {
+  const { fields, tags } = metadata;
+  const payload = {
+    measurement: measurement,
+    fields: fields,
+    tags: tags || {},
+    timestamp: new Date().toISOString(),
+  };
+  return JSON.stringify(payload);
+}
+
+module.exports = { format };

src/helper/formatters/processFormatter.js

@@ -0,0 +1,9 @@
+/**
+ * Process formatter
+ * Keeps the existing process-port behaviour: emit only changed fields as an object.
+ */
+function format(_measurement, metadata) {
+  return metadata.fields;
+}
+
+module.exports = { format };

src/helper/gravity.js

@@ -0,0 +1,90 @@
+/**
+ * Gravity calculations based on WGS-84 ellipsoid model.
+ * Author: Rene de Ren (Waterschap Brabantse Delta)
+ * License: EUPL-1.2
+ */
+
+class Gravity {
+  constructor() {
+    // Standard (conventional) gravity at 45° latitude, sea level
+    this.g0 = 9.80665; // m/s²
+  }
+
+  /**
+   * Returns standard gravity (constant)
+   * @returns {number} gravity in m/s²
+   */
+  getStandardGravity() {
+    return this.g0;
+  }
+
+  /**
+   * Computes local gravity based on latitude and elevation.
+   * Formula: WGS-84 normal gravity (Somigliana)
+   * @param {number} latitudeDeg  Latitude in degrees (−90 → +90)
+   * @param {number} elevationM   Elevation above sea level [m]
+   * @returns {number} gravity in m/s²
+   */
+  getLocalGravity(latitudeDeg, elevationM = 0) {
+    const phi = (latitudeDeg * Math.PI) / 180;
+    const sinPhi = Math.sin(phi);
+    const sin2 = sinPhi * sinPhi;
+    const sin2_2phi = Math.sin(2 * phi) ** 2;
+
+    // WGS-84 normal gravity on the ellipsoid
+    const gSurface =
+      9.780327 * (1 + 0.0053024 * sin2 - 0.0000058 * sin2_2phi);
+
+    // Free-air correction for elevation (~ −3.086×10⁻⁶ m/s² per m)
+    const gLocal = gSurface - 3.086e-6 * elevationM;
+    return gLocal;
+  }
+
+  /**
+   * Calculates hydrostatic pressure difference (ΔP = ρ g h)
+   * @param {number} density     Fluid density [kg/m³]
+   * @param {number} heightM     Height difference [m]
+   * @param {number} latitudeDeg Latitude (for local g)
+   * @param {number} elevationM  Elevation (for local g)
+   * @returns {number} Pressure difference [Pa]
+   */
+  pressureHead(density, heightM, latitudeDeg = 45, elevationM = 0) {
+    const g = this.getLocalGravity(latitudeDeg, elevationM);
+    return density * g * heightM;
+  }
+
+  /**
+   * Calculates weight force (F = m g)
+   * @param {number} massKg      Mass [kg]
+   * @param {number} latitudeDeg Latitude (for local g)
+   * @param {number} elevationM  Elevation (for local g)
+   * @returns {number} Force [N]
+   */
+  weightForce(massKg, latitudeDeg = 45, elevationM = 0) {
+    const g = this.getLocalGravity(latitudeDeg, elevationM);
+    return massKg * g;
+  }
+}
+
+module.exports = new Gravity();
+
+
+/*
+const gravity = gravity;
+
+// Standard gravity
+console.log('g₀ =', gravity.getStandardGravity(), 'm/s²');
+
+// Local gravity (Breda ≈ 51.6° N, 3 m elevation)
+console.log('g @ Breda =', gravity.getLocalGravity(51.6, 3).toFixed(6), 'm/s²');
+
+// Head pressure for 5 m water column at Breda
+console.log(
+  'ΔP =',
+  gravity.pressureHead(1000, 5, 51.6, 3).toFixed(1),
+  'Pa'
+);
+
+// Weight of 1 kg mass at Breda
+console.log('Weight =', gravity.weightForce(1, 51.6, 3).toFixed(6), 'N');
+*/

src/helper/index.js

@@ -0,0 +1,25 @@
+const assertions = require('./assertionUtils.js');
+const assetUtils = require('./assetUtils.js');
+const childRegistrationUtils = require('./childRegistrationUtils.js');
+const configUtils = require('./configUtils.js');
+const endpointUtils = require('./endpointUtils.js');
+const gravity = require('./gravity.js');
+const logger = require('./logger.js');
+const menuUtils = require('./menuUtils.js');
+const nodeTemplates = require('./nodeTemplates.js');
+const outputUtils = require('./outputUtils.js');
+const validation = require('./validationUtils.js');
+
+module.exports = {
+  assertions,
+  assetUtils,
+  childRegistrationUtils,
+  configUtils,
+  endpointUtils,
+  gravity,
+  logger,
+  menuUtils,
+  nodeTemplates,
+  outputUtils,
+  validation,
+};

src/helper/logger.js

@@ -44,7 +44,7 @@ class Logger {
       if (this.levels.includes(level)) {
         this.logLevel = level;
       } else {
-        console.error(`[ERROR ${this.nameModule}]: Invalid log level: ${level}`);
+        console.error(`[ERROR] -> ${this.nameModule}: Invalid log level: ${level}`);
       }
     }
   
@@ -54,4 +54,4 @@ class Logger {
     }
   }
   
-  module.exports = Logger;
+  module.exports = Logger;

src/helper/menu/htmlGeneration.js

@@ -16,17 +16,26 @@ const htmlGeneration = {
     }
   },
 
-  createMenuUtilsEndpoint(RED, nodeName, customHelpers = {}) {
-      RED.httpAdmin.get(`/${nodeName}/resources/menuUtils.js`, function(req, res) {
-        console.log(`Serving menuUtils.js for ${nodeName} node`);
-        res.set('Content-Type', 'application/javascript');
+  createMenuUtilsEndpoint(RED, nodeName, customHelpers = {}, options = {}) {
+    const basePath = `/${nodeName}/resources`;
 
-        const browserCode = this.generateMenuUtilsCode(nodeName, customHelpers);
-        res.send(browserCode);
-      }.bind(this));
-    },
+    RED.httpAdmin.get(`${basePath}/menuUtilsData.json`, function(req, res) {
+      res.json(this.generateMenuUtilsData(nodeName, customHelpers, options));
+    }.bind(this));
 
-  generateMenuUtilsCode(nodeName, customHelpers = {}) {
+    RED.httpAdmin.get(`${basePath}/menuUtils.legacy.js`, function(req, res) {
+      res.set('Content-Type', 'application/javascript');
+      const browserCode = this.generateLegacyMenuUtilsCode(nodeName, customHelpers);
+      res.send(browserCode);
+    }.bind(this));
+
+    RED.httpAdmin.get(`${basePath}/menuUtils.js`, function(req, res) {
+      res.set('Content-Type', 'application/javascript');
+      res.send(this.generateMenuUtilsBootstrap(nodeName));
+    }.bind(this));
+  },
+
+  generateMenuUtilsData(nodeName, customHelpers = {}, options = {}) {
     const defaultHelpers = {
       validateRequired: `function(value) {
         return value && value.toString().trim() !== '';
@@ -36,7 +45,71 @@ const htmlGeneration = {
       }`
     };
 
-    const allHelpers = { ...defaultHelpers, ...customHelpers };
+    return {
+      nodeName,
+      helpers: { ...defaultHelpers, ...customHelpers },
+      options: {
+        autoLoadLegacy: options.autoLoadLegacy !== false,
+      },
+    };
+  },
+
+  generateMenuUtilsBootstrap(nodeName) {
+    return `
+    // Stable bootstrap for EVOLV menu utils (${nodeName})
+    (function() {
+      const nodeName = ${JSON.stringify(nodeName)};
+      const basePath = '/' + nodeName + '/resources';
+
+      window.EVOLV = window.EVOLV || {};
+      window.EVOLV.nodes = window.EVOLV.nodes || {};
+      window.EVOLV.nodes[nodeName] = window.EVOLV.nodes[nodeName] || {};
+      window.EVOLV.nodes[nodeName].utils = window.EVOLV.nodes[nodeName].utils || {};
+
+      function parseHelper(fnBody) {
+        try {
+          return (new Function('return (' + fnBody + ')'))();
+        } catch (error) {
+          console.error('[menuUtils] helper parse failed:', error);
+          return function() { return null; };
+        }
+      }
+
+      function loadLegacyIfNeeded(autoLoadLegacy) {
+        if (!autoLoadLegacy || typeof window.MenuUtils === 'function') return Promise.resolve();
+        return new Promise((resolve, reject) => {
+          const script = document.createElement('script');
+          script.src = basePath + '/menuUtils.legacy.js';
+          script.onload = resolve;
+          script.onerror = reject;
+          document.head.appendChild(script);
+        });
+      }
+
+      fetch(basePath + '/menuUtilsData.json')
+        .then(function(res) { return res.json(); })
+        .then(function(payload) {
+          const helperFns = {};
+          Object.entries(payload.helpers || {}).forEach(function(entry) {
+            helperFns[entry[0]] = parseHelper(entry[1]);
+          });
+          window.EVOLV.nodes[nodeName].utils.helpers = helperFns;
+          return loadLegacyIfNeeded(payload.options && payload.options.autoLoadLegacy);
+        })
+        .then(function() {
+          if (typeof window.MenuUtils === 'function' && !window.EVOLV.nodes[nodeName].utils.menuUtils) {
+            window.EVOLV.nodes[nodeName].utils.menuUtils = new window.MenuUtils();
+          }
+        })
+        .catch(function(error) {
+          console.error('[menuUtils] bootstrap failed for ' + nodeName, error);
+        });
+    })();
+    `;
+  },
+
+  generateLegacyMenuUtilsCode(nodeName, customHelpers = {}) {
+    const allHelpers = { ...this.generateMenuUtilsData(nodeName).helpers, ...customHelpers };
 
     const helpersCode = Object.entries(allHelpers)
       .map(([name, func]) => `        ${name}: ${func}`)
@@ -58,7 +131,7 @@ const htmlGeneration = {
         menuUtils: new MenuUtils(),
 
         helpers: {
-  ${helpersCode}
+${helpersCode}
         }
       };
 
@@ -68,6 +141,11 @@ const htmlGeneration = {
       console.log('${nodeName} utilities loaded in namespace');
     `;
   },
+
+  // Backward-compatible alias
+  generateMenuUtilsCode(nodeName, customHelpers = {}) {
+    return this.generateLegacyMenuUtilsCode(nodeName, customHelpers);
+  },
 };
 
 module.exports = htmlGeneration;

src/helper/outputUtils.js

@@ -1,15 +1,29 @@
+const { getFormatter } = require('./formatters');
+
 //this class will handle the output events for the node red node
 class OutputUtils {
-  constructor() {
-    this.output ={};
-    this.output['influxdb'] = {};
-    this.output['process'] = {};
+  // `options.alwaysEmit` is an optional list of field keys that bypass delta
+  // compression: they are re-emitted on every tick even when unchanged. Use it
+  // sparingly for slowly-varying values that must still trace as a continuous
+  // line downstream (e.g. a pump's realized control position `ctrl`, which sits
+  // constant in steady state and otherwise produces ~1 point per long stretch —
+  // invisible in a Grafana timeseries with createEmpty:false). Defaults to none,
+  // so existing nodes keep pure delta-compression behaviour.
+  constructor(options = {}) {
+    this.output = {};
+    this.alwaysEmit = new Set(options.alwaysEmit || []);
   }
 
   checkForChanges(output, format) {
+    if (!output || typeof output !== 'object') {
+      return {};
+    }
+    this.output[format] = this.output[format] || {};
     const changedFields = {};
     for (const key in output) {
-      if (Object.prototype.hasOwnProperty.call(output, key) && output[key] !== this.output[format][key]) {
+      if (!Object.prototype.hasOwnProperty.call(output, key)) continue;
+      const forced = this.alwaysEmit.has(key) && output[key] !== undefined;
+      if (forced || output[key] !== this.output[format][key]) {
         let value = output[key];
         // For fields: if the value is an object (and not a Date), stringify it.
         if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
@@ -27,55 +41,47 @@ class OutputUtils {
   }
 
   formatMsg(output, config, format) {
-  
-    //define emtpy message
       let msg = {};
 
       // Compare output with last output and only include changed values
       const changedFields = this.checkForChanges(output,format);
 
       if (Object.keys(changedFields).length > 0) {
-
-        switch (format) {
-          case 'influxdb': {
-            // Extract the relevant config properties.
-            const relevantConfig = this.extractRelevantConfig(config);
-            // Flatten the tags so that no nested objects are passed on.
-            const flatTags = this.flattenTags(relevantConfig);
-            msg = this.influxDBFormat(changedFields, config, flatTags);
-
-            break;
-          }
-
-          case 'process':
-
-            // Compare output with last output and only include changed values
-            msg = this.processFormat(changedFields,config);
-            //console.log(msg);
-            break;
-
-          default:
-            console.log('Unknown format in output utils');
-            break;
-        }
+        // Fall back to `<softwareType>_<id>` when `general.name` is unset —
+        // the original convention before name became a registered config field.
+        const measurement = config.general.name
+          || `${config.functionality?.softwareType}_${config.general.id}`;
+        const flatTags = this.flattenTags(this.extractRelevantConfig(config));
+        const formatterName = this.resolveFormatterName(config, format);
+        const formatter = getFormatter(formatterName);
+        const payload = formatter.format(measurement, {
+          fields: changedFields,
+          tags: flatTags,
+          config,
+          channel: format,
+        });
+        msg = this.wrapMessage(measurement, payload);
         return msg;
       }
+      return null;
   }
-  
 
-  influxDBFormat(changedFields, config , flatTags) {
-    // Create the measurement and topic using softwareType and name config.functionality.softwareType + .
-    const measurement = config.general.name;
-    const payload = {
-      measurement: measurement,
-      fields: changedFields,
-      tags: flatTags,
-      timestamp: new Date(),
+  resolveFormatterName(config, channel) {
+    const outputConfig = config.output || {};
+    if (channel === 'process') {
+      return outputConfig.process || 'process';
+    }
+    if (channel === 'influxdb') {
+      return outputConfig.dbase || 'influxdb';
+    }
+    return outputConfig[channel] || channel;
+  }
+
+  wrapMessage(measurement, payload) {
+    return {
+      topic: measurement,
+      payload,
     };
-
-    const topic = measurement;
-    const msg = { topic: topic, payload: payload };
-    return msg;
   }
 
   flattenTags(obj) {
@@ -83,7 +89,13 @@ class OutputUtils {
     for (const key in obj) {
       if (Object.prototype.hasOwnProperty.call(obj, key)) {
         const value = obj[key];
-        if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
+        // Skip tags that carry no information. When a config field is unset,
+        // extractRelevantConfig hands us `undefined`; stringifying that wrote
+        // literal `category="undefined"` / `geoLocation="undefined"` tags that
+        // clutter every Grafana legend and needlessly inflate tag cardinality.
+        // Drop null / undefined / empty-string before they reach InfluxDB.
+        if (value === null || value === undefined || value === '') continue;
+        if (typeof value === 'object' && !(value instanceof Date)) {
           // Recursively flatten the nested object.
           const flatChild = this.flattenTags(value);
           for (const childKey in flatChild) {
@@ -101,33 +113,24 @@ class OutputUtils {
   }
 
   extractRelevantConfig(config) {
-    
+
     return {
       // general properties
       id: config.general?.id,
-      name: config.general?.name,
-      unit: config.general?.unit,
       // functionality properties
       softwareType: config.functionality?.softwareType,
       role: config.functionality?.role,
+      positionVsParent: config.functionality?.positionVsParent,
       // asset properties (exclude machineCurve)
       uuid: config.asset?.uuid,
+      tagcode: config.asset?.tagCode || config.asset?.tagcode,
       geoLocation: config.asset?.geoLocation,
-      supplier: config.asset?.supplier,
+      category: config.asset?.category,
       type: config.asset?.type,
-      subType: config.asset?.subType,
       model: config.asset?.model,
+      unit: config.general?.unit,
     };
   }
-
-  processFormat(changedFields,config) {
-        // Create the measurement and topic using softwareType and name config.functionality.softwareType + .
-        const measurement = config.general.name;
-        const payload = changedFields;
-        const topic = measurement;
-        const msg = { topic: topic, payload: payload };
-        return msg;
-  }
 }
 
 module.exports = OutputUtils;

src/helper/validationUtils.js

@@ -50,11 +50,24 @@ const VALIDATORS = {
 
 class ValidationUtils {
   constructor(IloggerEnabled, IloggerLevel) {
-        const loggerEnabled = IloggerEnabled || true;
-        const loggerLevel = IloggerLevel || "warn";
+        const loggerEnabled = IloggerEnabled ?? true;
+        const loggerLevel = IloggerLevel ?? "warn";
         this.logger = new Logger(loggerEnabled, loggerLevel, 'ValidationUtils');
+        this._onceLogCache = new Set();
   }
 
+    _logOnce(level, onceKey, message) {
+        if (onceKey && this._onceLogCache.has(onceKey)) {
+            return;
+        }
+        if (onceKey) {
+            this._onceLogCache.add(onceKey);
+        }
+        if (typeof this.logger?.[level] === "function") {
+            this.logger[level](message);
+        }
+    }
+
     constrain(value, min, max) {
         if (typeof value !== "number") {
             this.logger?.warn(`Value '${value}' is not a number. Defaulting to ${min}.`);
@@ -82,11 +95,19 @@ class ValidationUtils {
         // Validate each key in the schema and loop over wildcards if they are not in schema
         for ( const key in schema ) {
 
-            if (key === "rules" || key === "description" || key === "schema") {
+            if (key === "rules" || key === "description" || key === "schema" || key === "version") {
                 continue;
               }
 
             const fieldSchema = schema[key];
+
+            // Skip non-object schema entries (e.g. primitive values injected by migration)
+            if (fieldSchema === null || typeof fieldSchema !== 'object') {
+                this.logger.debug(`${name}.${key} has a non-object schema entry (${typeof fieldSchema}). Skipping.`);
+                validatedConfig[key] = fieldSchema;
+                continue;
+            }
+
             const { rules = {} } = fieldSchema;
 
             // Default to the schema's default value if the key is missing
@@ -110,7 +131,7 @@ class ValidationUtils {
                     continue;
                     }
                 } else {
-                    this.logger.info(`There is no value provided for ${name}.${key}. Using default value.`);
+                    this.logger.debug(`No value provided for ${name}.${key}. Using default value.`);
                     configValue = fieldSchema.default;
                 }
                 //continue;
@@ -186,7 +207,7 @@ class ValidationUtils {
               continue;
             }
 
-            if("default" in v){
+            if(v && typeof v === "object" && "default" in v){
                 //put the default value in the object
                 newObj[k] = v.default;
                 continue;
@@ -212,6 +233,13 @@ class ValidationUtils {
                 return fieldSchema.default;
             }
     }
+
+    // Public wrapper for the curve validator — exposes the helper so
+    // callers (and tests) can validate a raw curve without going
+    // through validateSchema.
+    validateCurve(input, defaultCurve) {
+        return validateCurve(input, defaultCurve, this.logger);
+    }
 }
 
 module.exports = ValidationUtils;

src/helper/validators/collectionValidators.js

@@ -17,7 +17,7 @@ function validateArray(configValue, rules, fieldSchema, name, key, logger) {
             }
         })
         .slice(0, rules.maxLength || Infinity);
-    if (validatedArray.length < (rules.minLength || 1)) {
+    if (validatedArray.length < (rules.minLength ?? 1)) {
         logger.warn(
             `${name}.${key} contains fewer items than allowed (${rules.minLength}). Using default value.`
         );
@@ -41,7 +41,7 @@ function validateSet(configValue, rules, fieldSchema, name, key, logger) {
             }
         })
         .slice(0, rules.maxLength || Infinity);
-    if (validatedArray.length < (rules.minLength || 1)) {
+    if (validatedArray.length < (rules.minLength ?? 1)) {
         logger.warn(
             `${name}.${key} contains fewer items than allowed (${rules.minLength}). Using default value.`
         );

src/helper/validators/typeValidators.js

@@ -56,35 +56,83 @@ function validateBoolean(configValue, name, key, logger) {
     return configValue;
 }
 
+function _isUnitLikeField(path) {
+    const normalized = String(path || "").toLowerCase();
+    if (!normalized) return false;
+    return /(^|\.)([a-z0-9]*unit|units)(\.|$)/.test(normalized)
+        || normalized.includes(".curveunits.");
+}
+
+function _resolveStringNormalizeMode(path) {
+    const normalized = String(path || "").toLowerCase();
+    if (!normalized) return "none";
+
+    if (_isUnitLikeField(normalized)) return "none";
+    if (normalized.endsWith(".name")) return "none";
+    if (normalized.endsWith(".model")) return "none";
+    if (normalized.endsWith(".supplier")) return "none";
+    if (normalized.endsWith(".role")) return "none";
+    if (normalized.endsWith(".description")) return "none";
+
+    if (normalized.endsWith(".softwaretype")) return "lowercase";
+    if (normalized.endsWith(".type")) return "lowercase";
+    if (normalized.endsWith(".category")) return "lowercase";
+
+    return "lowercase";
+}
+
 function validateString(configValue, rules, fieldSchema, name, key, logger) {
     let newConfigValue = configValue;
+
     if (typeof configValue !== "string") {
+        //check if the value is nullable
         if(rules.nullable){
             if(configValue === null){
                 return null;
             }
         }
+
         logger.warn(`${name}.${key} is not a string. Trying to convert to string.`);
-        newConfigValue = String(configValue);
+        newConfigValue = String(configValue); // Coerce to string if not already
     }
+
+    //check if the string is a valid string after conversion
     if (typeof newConfigValue !== "string") {
         logger.warn(`${name}.${key} is not a valid string. Using default value.`);
         return fieldSchema.default;
     }
-    if (newConfigValue !== newConfigValue.toLowerCase()) {
-        logger.warn(`${name}.${key} contains uppercase characters. Converting to lowercase: ${newConfigValue} -> ${newConfigValue.toLowerCase()}`);
+
+    const keyString = `${name}.${key}`;
+    const normalizeMode = rules.normalize || _resolveStringNormalizeMode(keyString);
+    const preserveCase = normalizeMode !== "lowercase";
+
+    // Check for uppercase characters and convert to lowercase if present
+    if (!preserveCase && newConfigValue !== newConfigValue.toLowerCase()) {
+        logger.info(
+            `${name}.${key} normalized to lowercase: ${newConfigValue} -> ${newConfigValue.toLowerCase()}`
+        );
         newConfigValue = newConfigValue.toLowerCase();
     }
+
     return newConfigValue;
 }
 
 function validateEnum(configValue, rules, fieldSchema, name, key, logger) {
     if (Array.isArray(rules.values)) {
+        //if value is null take default
         if(configValue === null){
             logger.warn(`${name}.${key} is null. Using default value.`);
             return fieldSchema.default;
         }
+
+        if (typeof configValue !== "string") {
+            logger.warn(`${name}.${key} is not a valid enum string. Using default value.`);
+            return fieldSchema.default;
+        }
+
         const validValues = rules.values.map(e => e.value.toLowerCase());
+
+        //remove caps
         configValue = configValue.toLowerCase();
         if (!validValues.includes(configValue)) {
             logger.warn(

src/measurements/Measurement.js

@@ -69,8 +69,10 @@ class Measurement {
   }
 
   getLaggedValue(lag){
-    if(this.values.length <= lag) return null;
-    return this.values[this.values.length - lag];
+    if (lag < 0) throw new Error('lag must be >= 0');
+    const index = this.values.length - 1 - lag;
+    if (index < 0) return null;
+    return this.values[index];
   }
 
   getLaggedSample(lag){
@@ -177,7 +179,7 @@ class Measurement {
     
     try {
       const convertedValues = this.values.map(value => 
-        convertModule.convert(value).from(this.unit).to(targetUnit)
+        convertModule(value).from(this.unit).to(targetUnit)
       );
       
       const newMeasurement = new Measurement(

src/measurements/MeasurementContainer.js

@@ -3,20 +3,67 @@ const EventEmitter = require('events');
 const convertModule = require('../convert/index');
 const { POSITIONS } = require('../constants/positions');
 
+/* ============================================================================
+ * MeasurementContainer — measurement storage with chainable type/variant/
+ * position/child addressing.
+ *
+ * INTERNAL STORAGE SHAPE
+ *   measurements[type][variant][position][childId] = Measurement instance
+ *
+ * The childId layer is ALWAYS present, even when the caller doesn't specify
+ * one. _getOrCreateMeasurement defaults childId to 'default' when no
+ * .child(...) is in the chain. So writing
+ *
+ *     mc.type('level').variant('measured').position('atequipment')
+ *       .value(2.5, ts, 'm');
+ *
+ * stores the value at  measurements.level.measured.atequipment.default.
+ *
+ * READING — the chainable getters resolve the default child transparently,
+ * so consumers usually don't see it:
+ *
+ *     mc.type('level').variant('measured').position('atequipment')
+ *       .getCurrentValue('m');     // returns 2.5
+ *
+ * FLATTENED OUTPUT — getFlattenedOutput() emits ONE key per child, including
+ * the implicit 'default' bucket:
+ *
+ *     {
+ *       'level.measured.atequipment.default': 2.5,           // implicit child
+ *       'flow.predicted.in.manual-qin':       0.05,          // explicit .child('manual-qin')
+ *       'flow.predicted.in.from-pump-A':      0.03,
+ *       …
+ *     }
+ *
+ * ⚠ DASHBOARDS / DOWNSTREAM PARSERS MUST INCLUDE THE CHILD KEY
+ *   The flat key format is `${type}.${variant}.${position}.${childId}`.
+ *   When you have not used .child(), the childId is the literal string
+ *   'default'. Use 'level.measured.atequipment.default', NOT
+ *   'level.measured.atequipment'. This trips up new consumers — see the
+ *   pumpingStation basic-dashboard parser for an example that gets it right.
+ *
+ * AGGREGATION — sum() folds all children of a position into one number:
+ *
+ *     mc.sum('flow', 'predicted', ['in'], 'm3/s');
+ *     // = manual-qin + from-pump-A + … + (default if any)
+ * ============================================================================
+ */
 class MeasurementContainer {
-  constructor(options = {},_logger) {
+  constructor(options = {},logger) {
+    this.logger = logger || null;
     this.emitter = new EventEmitter();
     this.measurements = {};
     this.windowSize = options.windowSize || 10; // Default window size
     
     // For chaining context
+    this._currentChildId = null;
     this._currentType = null;
     this._currentVariant = null;
     this._currentPosition = null;
     this._currentDistance = null;
     this._unit = null;
 
-    // Default units for each measurement type
+    // Default units for each measurement type (ingress/preferred)
     this.defaultUnits = {
       pressure: 'mbar',
       flow: 'm3/h',
@@ -26,10 +73,48 @@ class MeasurementContainer {
       length: 'm',
       ...options.defaultUnits // Allow override
     };
+
+    // Canonical storage unit map (single conversion anchor per measurement type)
+    this.canonicalUnits = {
+      pressure: 'Pa',
+      atmPressure: 'Pa',
+      flow: 'm3/s',
+      power: 'W',
+      hydraulicPower: 'W',
+      temperature: 'K',
+      volume: 'm3',
+      length: 'm',
+      mass: 'kg',
+      energy: 'J',
+      ...options.canonicalUnits,
+    };
     
     // Auto-conversion settings
     this.autoConvert = options.autoConvert !== false; // Default to true
     this.preferredUnits = options.preferredUnits || {}; // Per-measurement overrides
+    this.storeCanonical = options.storeCanonical === true;
+    this.strictUnitValidation = options.strictUnitValidation === true;
+    this.throwOnInvalidUnit = options.throwOnInvalidUnit === true;
+    this.requireUnitForTypes = new Set(
+      (options.requireUnitForTypes || []).map((t) => String(t).trim().toLowerCase())
+    );
+
+    // Map EVOLV measurement types to convert-module measure families
+    this.measureMap = {
+      pressure: 'pressure',
+      atmpressure: 'pressure',
+      flow: 'volumeFlowRate',
+      power: 'power',
+      hydraulicpower: 'power',
+      reactivepower: 'reactivePower',
+      apparentpower: 'apparentPower',
+      temperature: 'temperature',
+      volume: 'volume',
+      length: 'length',
+      mass: 'mass',
+      energy: 'energy',
+      reactiveenergy: 'reactiveEnergy',
+    };
     
     // For chaining context
     this._currentType = null;
@@ -50,6 +135,11 @@ class MeasurementContainer {
       return this;
   }
 
+  child(childId) {
+    this._currentChildId = childId || 'default';
+    return this;
+  }
+
   setChildName(childName) {
       this.childName = childName;
       return this;
@@ -66,6 +156,11 @@ class MeasurementContainer {
     return this;
   }
 
+  setCanonicalUnit(measurementType, unit) {
+    this.canonicalUnits[measurementType] = unit;
+    return this;
+  }
+
   // Get the target unit for a measurement type
   _getTargetUnit(measurementType) {
     return this.preferredUnits[measurementType] || 
@@ -73,29 +168,120 @@ class MeasurementContainer {
            null;
   }
 
+  _getCanonicalUnit(measurementType) {
+    return this.canonicalUnits[measurementType] || null;
+  }
+
+  _normalizeType(measurementType) {
+    return String(measurementType || '').trim().toLowerCase();
+  }
+
+  _describeUnit(unit) {
+    if (typeof unit !== 'string' || unit.trim() === '') return null;
+    try {
+      return convertModule().describe(unit.trim());
+    } catch (error) {
+      return null;
+    }
+  }
+
+  isUnitCompatible(measurementType, unit) {
+    // Unknown type (not in measureMap): accept any unit. This lets user-
+    // defined measurement types (e.g. 'humidity', 'co2', arbitrary IoT
+    // channels in digital mode) pass through without being rejected just
+    // because their unit string ('%', 'ppm', …) is not a known physical
+    // unit to the convert module. Known types are still validated strictly.
+    const normalizedType = this._normalizeType(measurementType);
+    const expectedMeasure = this.measureMap[normalizedType];
+    if (!expectedMeasure) return true;
+
+    const desc = this._describeUnit(unit);
+    if (!desc) return false;
+    return desc.measure === expectedMeasure;
+  }
+
+  _handleUnitViolation(message) {
+    if (this.throwOnInvalidUnit) {
+      throw new Error(message);
+    }
+    if (this.logger) {
+      this.logger.warn(message);
+    }
+  }
+
+  _resolveUnitPolicy(measurementType, sourceUnit = null) {
+    const normalizedType = this._normalizeType(measurementType);
+    const rawSourceUnit = typeof sourceUnit === 'string' && sourceUnit.trim()
+      ? sourceUnit.trim()
+      : null;
+    const fallbackIngressUnit = this._getTargetUnit(measurementType);
+    const canonicalUnit = this._getCanonicalUnit(measurementType);
+    const resolvedSourceUnit = rawSourceUnit || fallbackIngressUnit || canonicalUnit || null;
+
+    if (this.requireUnitForTypes.has(normalizedType) && !rawSourceUnit) {
+      this._handleUnitViolation(`Missing source unit for required measurement type '${measurementType}'.`);
+      return { valid: false };
+    }
+
+    if (resolvedSourceUnit && !this.isUnitCompatible(measurementType, resolvedSourceUnit)) {
+      this._handleUnitViolation(`Incompatible or unknown source unit '${resolvedSourceUnit}' for measurement type '${measurementType}'.`);
+      return { valid: false };
+    }
+
+    const resolvedStorageUnit = this.storeCanonical
+      ? (canonicalUnit || fallbackIngressUnit || resolvedSourceUnit)
+      : (fallbackIngressUnit || canonicalUnit || resolvedSourceUnit);
+
+    if (resolvedStorageUnit && !this.isUnitCompatible(measurementType, resolvedStorageUnit)) {
+      this._handleUnitViolation(`Incompatible storage unit '${resolvedStorageUnit}' for measurement type '${measurementType}'.`);
+      return { valid: false };
+    }
+
+    return {
+      valid: true,
+      sourceUnit: resolvedSourceUnit,
+      storageUnit: resolvedStorageUnit || null,
+      strictValidation: this.strictUnitValidation,
+    };
+  }
+
+  getUnit(type) {
+    if (!type) return null;
+    if (this.preferredUnits && this.preferredUnits[type]) return this.preferredUnits[type];
+    if (this.defaultUnits && this.defaultUnits[type]) return this.defaultUnits[type];
+    return null;
+  }
+
   // Chainable methods
   type(typeName) {
     this._currentType = typeName;
     this._currentVariant = null;
     this._currentPosition = null;
+    this._currentChildId = null;
     return this;
   }
 
   variant(variantName) {
     if (!this._currentType) {
-      throw new Error('Type must be specified before variant');
+      if (this.logger) {
+        this.logger.warn('variant() ignored: type must be specified before variant');
+      }
+      return this;
     }
     this._currentVariant = variantName;
     this._currentPosition = null;
+    this._currentChildId = null;
     return this;
   }
 
   position(positionValue) {
     if (!this._currentVariant) {
-      throw new Error('Variant must be specified before position');
+      if (this.logger) {
+        this.logger.warn('position() ignored: variant must be specified before position');
+      }
+      return this;
     }
 
-    
     this._currentPosition = positionValue.toString().toLowerCase();
     
     return this;
@@ -115,34 +301,40 @@ class MeasurementContainer {
   // ENHANCED: Update your existing value method
   value(val, timestamp = Date.now(), sourceUnit = null) {
       if (!this._ensureChainIsValid()) return this;
-      
+
+      const unitPolicy = this._resolveUnitPolicy(this._currentType, sourceUnit);
+      if (!unitPolicy.valid) return this;
+
       const measurement = this._getOrCreateMeasurement();
-      const targetUnit = this._getTargetUnit(this._currentType);
-      
+      const targetUnit = unitPolicy.storageUnit;
+
       let convertedValue = val;
-      let finalUnit = sourceUnit || targetUnit;
+      let finalUnit = targetUnit || unitPolicy.sourceUnit;
 
       // Auto-convert if enabled and units are specified
-      if (this.autoConvert && sourceUnit && targetUnit && sourceUnit !== targetUnit) {
+      if (this.autoConvert && unitPolicy.sourceUnit && targetUnit && unitPolicy.sourceUnit !== targetUnit) {
         try {
-          convertedValue = convertModule(val).from(sourceUnit).to(targetUnit);
+          convertedValue = convertModule(val).from(unitPolicy.sourceUnit).to(targetUnit);
           finalUnit = targetUnit;
           
           if (this.logger) {
-            this.logger.debug(`Auto-converted ${val} ${sourceUnit} to ${convertedValue} ${targetUnit}`);
+            this.logger.debug(`Auto-converted ${val} ${unitPolicy.sourceUnit} to ${convertedValue} ${targetUnit}`);
           }
         } catch (error) {
-          if (this.logger) {
-            this.logger.warn(`Auto-conversion failed from ${sourceUnit} to ${targetUnit}: ${error.message}`);
+          const message = `Auto-conversion failed from ${unitPolicy.sourceUnit} to ${targetUnit}: ${error.message}`;
+          if (this.strictUnitValidation) {
+            this._handleUnitViolation(message);
+            return this;
           }
+          if (this.logger) this.logger.warn(message);
           convertedValue = val;
-          finalUnit = sourceUnit;
+          finalUnit = unitPolicy.sourceUnit;
         }
       }
 
       measurement.setValue(convertedValue, timestamp);
       
-      if (finalUnit && !measurement.unit) {
+      if (finalUnit) {
         measurement.setUnit(finalUnit);
       }
 
@@ -151,7 +343,7 @@ class MeasurementContainer {
         value: convertedValue,
         originalValue: val,
         unit: finalUnit,
-        sourceUnit: sourceUnit,
+        sourceUnit: unitPolicy.sourceUnit,
         timestamp,
         position: this._currentPosition,
         distance: this._currentDistance,
@@ -213,8 +405,6 @@ class MeasurementContainer {
     return requireValues ? measurement.values?.length > 0 : true;
   }
 
-
-
   unit(unitName) {
     if (!this._ensureChainIsValid()) return this;
     
@@ -225,36 +415,65 @@ class MeasurementContainer {
   }
 
   // Terminal operations - get data out
-  get() {
-    if (!this._ensureChainIsValid()) return null;
-    return this._getOrCreateMeasurement();
-  }
+    get() {
+      if (!this._ensureChainIsValid()) return null;
+      const variantBucket = this.measurements[this._currentType]?.[this._currentVariant];
+      if (!variantBucket) return null;
+      const posBucket = variantBucket[this._currentPosition];
+      if (!posBucket) return null;
+
+      // Legacy single measurement
+      if (posBucket?.getCurrentValue) return posBucket;
+
+      // Child-aware lookup. Two separate sources of "child-id" on the
+      // container, with DIFFERENT strictness:
+      //
+      //   _currentChildId : transient, set by .child(name) inside a chain.
+      //                     Explicit per-call. STRICT — if the named child
+      //                     does not exist, return null. Silent fall-through
+      //                     to a sibling would mask a missing-stream read
+      //                     as a wrong-stream read (see pumpingStation
+      //                     spillPrev bug, 2026-05-06).
+      //
+      //   this.childId    : persistent, set by setChildId(id). HINT only —
+      //                     try it first, then fall back to 'default' then
+      //                     first available. Containers registered with a
+      //                     persistent id (rotatingMachine, etc.) write
+      //                     under composed child ids (e.g. 'up-<id>') that
+      //                     don't equal the persistent id, and reads must
+      //                     still resolve to those writes.
+      if (posBucket && typeof posBucket === 'object') {
+        const keys = Object.keys(posBucket);
+        if (!keys.length) return null;
+
+        if (this._currentChildId) {
+          return posBucket[this._currentChildId] || null;
+        }
+        return (this.childId && posBucket[this.childId]) ||
+               posBucket.default ||
+               posBucket[keys[0]] ||
+               null;
+      }
+
+      return null;
+    }
+
+
 
   getCurrentValue(requestedUnit = null) {
     const measurement = this.get();
     if (!measurement) return null;
-    
     const value = measurement.getCurrentValue();
     if (value === null) return null;
-
-    // Return as-is if no unit conversion requested
-    if (!requestedUnit) {
+    if (!requestedUnit || !measurement.unit || requestedUnit === measurement.unit) {
       return value;
     }
-
-    // Convert if needed
-    if (measurement.unit && requestedUnit !== measurement.unit) {
-      try {
-        return convertModule(value).from(measurement.unit).to(requestedUnit);
-      } catch (error) {
-        if (this.logger) {
-          this.logger.error(`Unit conversion failed: ${error.message}`);
-        }
-        return value; // Return original value if conversion fails
-      }
+    try {
+      return convertModule(value).from(measurement.unit).to(requestedUnit);
+    } catch (error) {
+      if (this.logger) this.logger.error(`Unit conversion failed: ${error.message}`);
+      return value;
     }
-
-    return value;
   }
 
   getAverage(requestedUnit = null) {
@@ -309,7 +528,7 @@ class MeasurementContainer {
     // Convert if needed
     if (measurement.unit && requestedUnit !== measurement.unit) {
       try {
-        const convertedValue = convertModule(value).from(measurement.unit).to(requestedUnit);
+        const convertedValue = convertModule(sample.value).from(measurement.unit).to(requestedUnit);
         //replace old value in sample and return obj
         sample.value = convertedValue ;
         sample.unit = requestedUnit;
@@ -358,38 +577,114 @@ class MeasurementContainer {
     return sample;
   }
 
+  sum(type, variant, positions = [], targetUnit = null) {
+    const bucket = this.measurements?.[type]?.[variant];
+    if (!bucket) return 0;
+    return positions
+      .map((pos) => {
+        const posBucket = bucket[pos];
+        if (!posBucket) return 0;
+        return Object.values(posBucket)
+          .map((m) => {
+            if (!m?.getCurrentValue) return 0;
+            const val = m.getCurrentValue();
+            if (val == null) return 0;
+            const fromUnit = m.unit || targetUnit;
+            if (!targetUnit || !fromUnit || fromUnit === targetUnit) return val;
+            try { return convertModule(val).from(fromUnit).to(targetUnit); } catch { return val; }
+          })
+          .reduce((acc, v) => acc + (Number.isFinite(v) ? v : 0), 0);
+      })
+      .reduce((acc, v) => acc + v, 0);
+  }
+
+    /**
+     * Flatten the entire container to a key→value map, suitable for
+     * dashboards / InfluxDB / debug dumps.
+     *
+     * KEY FORMAT — child-bucketed series (the common case):
+     *   `${type}.${variant}.${position}.${childId}`
+     *
+     * Even measurements written without an explicit `.child(...)` end up
+     * here under `childId === 'default'` (see _getOrCreateMeasurement).
+     * Examples:
+     *   level.measured.atequipment.default     // implicit child
+     *   flow.predicted.in.manual-qin           // explicit child
+     *   flow.predicted.in.from-pump-A          // explicit child
+     *
+     * Consumers (Node-RED dashboards, parsers) MUST include the trailing
+     * `.default` when reading default-bucket measurements. Stripping it
+     * silently misses the value. This is the #1 footgun for new code that
+     * uses MeasurementContainer.
+     *
+     * The "Legacy single series" branch below catches a pre-v2 storage
+     * shape where a position held a Measurement directly (no child layer);
+     * new code never produces that shape but old serialized state may.
+     */
+    getFlattenedOutput(options = {}) {
+      const requestedUnits = options.requestedUnits || (options.usePreferredUnits ? this.preferredUnits : null);
+      const out = {};
+      Object.entries(this.measurements).forEach(([type, variants]) => {
+        Object.entries(variants).forEach(([variant, positions]) => {
+          Object.entries(positions).forEach(([position, entry]) => {
+            // Legacy single series (no childId layer)
+            if (entry?.getCurrentValue) {
+              out[`${type}.${variant}.${position}`] = this._resolveOutputValue(type, entry, requestedUnits);
+              return;
+            }
+            // Child-bucketed series — ALWAYS the case for new writes,
+            // including the implicit 'default' bucket when no .child() is
+            // used. The flat key carries the childId.
+            if (entry && typeof entry === 'object') {
+              Object.entries(entry).forEach(([childId, m]) => {
+                if (m?.getCurrentValue) {
+                  out[`${type}.${variant}.${position}.${childId}`] = this._resolveOutputValue(type, m, requestedUnits);
+                }
+              });
+            }
+          });
+        });
+      });
+      return out;
+  }
 
   // Difference calculations between positions
-difference({ from = POSITIONS.DOWNSTREAM, to = POSITIONS.UPSTREAM, unit: requestedUnit } = {}) {
-  if (!this._currentType || !this._currentVariant) {
-    throw new Error("Type and variant must be specified for difference calculation");
+  difference({ from = POSITIONS.DOWNSTREAM, to = POSITIONS.UPSTREAM, unit: requestedUnit } = {}) {
+    if (!this._currentType || !this._currentVariant) {
+      if (this.logger) {
+        this.logger.warn('difference() ignored: type and variant must be specified');
+      }
+      return null;
+    }
+
+    const get = pos => {
+      const bucket = this.measurements?.[this._currentType]?.[this._currentVariant]?.[pos];
+      if (!bucket) return null;
+      // child-aware bucket: pick current childId/default or first available
+      if (bucket && typeof bucket === 'object' && !bucket.getCurrentValue) {
+        const childKey = this._currentChildId || this.childId || Object.keys(bucket)[0];
+        return bucket?.[childKey] || null;
+      }
+      // legacy single measurement
+      return bucket;
+    };
+
+    const a = get(from);
+    const b = get(to);
+    if (!a || !b || !a.values || !b.values || a.values.length === 0 || b.values.length === 0) {
+      return null;
+    }
+
+    const targetUnit = requestedUnit || a.unit || b.unit;
+    const aVal = this._convertValueToUnit(a.getCurrentValue(), a.unit, targetUnit);
+    const bVal = this._convertValueToUnit(b.getCurrentValue(), b.unit, targetUnit);
+
+    const aAvg = this._convertValueToUnit(a.getAverage(), a.unit, targetUnit);
+    const bAvg = this._convertValueToUnit(b.getAverage(), b.unit, targetUnit);
+
+    return { value: aVal - bVal, avgDiff: aAvg - bAvg, unit: targetUnit, from, to };
   }
 
-  const get = pos =>
-    this.measurements?.[this._currentType]?.[this._currentVariant]?.[pos] || null;
-
-  const a = get(from);
-  const b = get(to);
-  if (!a || !b || a.values.length === 0 || b.values.length === 0) {
-    return null;
-  }
-
-  const targetUnit = requestedUnit || a.unit || b.unit;
-  const aVal = this._convertValueToUnit(a.getCurrentValue(), a.unit, targetUnit);
-  const bVal = this._convertValueToUnit(b.getCurrentValue(), b.unit, targetUnit);
-
-  const aAvg = this._convertValueToUnit(a.getAverage(), a.unit, targetUnit);
-  const bAvg = this._convertValueToUnit(b.getAverage(), b.unit, targetUnit);
-
-  return {
-    value: aVal - bVal,
-    avgDiff: aAvg - bAvg,
-    unit: targetUnit,
-    from,
-    to,
-  };
-}
-
   // Helper methods
   _ensureChainIsValid() {
     if (!this._currentType || !this._currentVariant || !this._currentPosition) {
@@ -411,18 +706,26 @@ difference({ from = POSITIONS.DOWNSTREAM, to = POSITIONS.UPSTREAM, unit: request
       this.measurements[this._currentType][this._currentVariant] = {};
     }
     
-    if (!this.measurements[this._currentType][this._currentVariant][this._currentPosition]) {
-      this.measurements[this._currentType][this._currentVariant][this._currentPosition] = 
-        new MeasurementBuilder()
-          .setType(this._currentType)
-          .setVariant(this._currentVariant)
-          .setPosition(this._currentPosition)
-          .setWindowSize(this.windowSize)
-          .setDistance(this._currentDistance)
-          .build();
+    const positionKey = this._currentPosition;
+    const childKey = this._currentChildId || this.childId || 'default';
+
+    if (!this.measurements[this._currentType][this._currentVariant][positionKey]) {
+      this.measurements[this._currentType][this._currentVariant][positionKey] = {};
     }
-    
-    return this.measurements[this._currentType][this._currentVariant][this._currentPosition];
+
+    const bucket = this.measurements[this._currentType][this._currentVariant][positionKey];
+
+    if (!bucket[childKey]) {
+      bucket[childKey] = new MeasurementBuilder()
+        .setType(this._currentType)
+        .setVariant(this._currentVariant)
+        .setPosition(positionKey)
+        .setWindowSize(this.windowSize)
+        .setDistance(this._currentDistance)
+        .build();
+    }
+
+    return bucket[childKey];
   }
 
   // Additional utility methods
@@ -432,15 +735,33 @@ difference({ from = POSITIONS.DOWNSTREAM, to = POSITIONS.UPSTREAM, unit: request
 
   getVariants() {
     if (!this._currentType) {
-      throw new Error('Type must be specified before listing variants');
+      if (this.logger) {
+        this.logger.warn('getVariants() ignored: type must be specified first');
+      }
+      return [];
     }
     return this.measurements[this._currentType] ? 
       Object.keys(this.measurements[this._currentType]) : [];
   }
 
+  _resolveOutputValue(type, measurement, requestedUnits = null) {
+    const value = measurement.getCurrentValue();
+    if (!requestedUnits || value === null || typeof value === 'undefined') {
+      return value;
+    }
+    const targetUnit = requestedUnits[type];
+    if (!targetUnit) {
+      return value;
+    }
+    return this._convertValueToUnit(value, measurement.unit, targetUnit);
+  }
+
   getPositions() {
     if (!this._currentType || !this._currentVariant) {
-      throw new Error('Type and variant must be specified before listing positions');
+      if (this.logger) {
+        this.logger.warn('getPositions() ignored: type and variant must be specified first');
+      }
+      return [];
     }
     
     if (!this.measurements[this._currentType] || 
@@ -462,7 +783,7 @@ difference({ from = POSITIONS.DOWNSTREAM, to = POSITIONS.UPSTREAM, unit: request
 
   // Helper method for value conversion
   _convertValueToUnit(value, fromUnit, toUnit) {
-    if (!value || !fromUnit || !toUnit || fromUnit === toUnit) {
+    if ((value === null || typeof value === 'undefined') || !fromUnit || !toUnit || fromUnit === toUnit) {
       return value;
     }
 
@@ -481,19 +802,7 @@ difference({ from = POSITIONS.DOWNSTREAM, to = POSITIONS.UPSTREAM, unit: request
     const type = measurementType || this._currentType;
     if (!type) return [];
 
-    // Map measurement types to convert module measures
-    const measureMap = {
-      pressure: 'pressure',
-      flow: 'volumeFlowRate',
-      power: 'power',
-      temperature: 'temperature',
-      volume: 'volume',
-      length: 'length',
-      mass: 'mass',
-      energy: 'energy'
-    };
-
-    const convertMeasure = measureMap[type];
+    const convertMeasure = this.measureMap[this._normalizeType(type)];
     if (!convertMeasure) return [];
 
     try {
@@ -543,16 +852,19 @@ difference({ from = POSITIONS.DOWNSTREAM, to = POSITIONS.UPSTREAM, unit: request
   }
 
   _convertPositionNum2Str(positionValue) {
-    switch (positionValue) {
-    case 0:
+    if (positionValue === 0) {
       return POSITIONS.AT_EQUIPMENT;
-    case (positionValue < 0):
-      return POSITIONS.UPSTREAM;
-    case (positionValue > 0):
-      return POSITIONS.DOWNSTREAM;
-    default:
-      console.log(`Invalid position provided: ${positionValue}`);
     }
+    if (positionValue < 0) {
+      return POSITIONS.UPSTREAM;
+    }
+    if (positionValue > 0) {
+      return POSITIONS.DOWNSTREAM;
+    }
+    if (this.logger) {
+      this.logger.warn(`Invalid position provided: ${positionValue}`);
+    }
+    return null;
   }
 
 }

src/measurements/examples.js

@@ -180,18 +180,18 @@ const downstreamData = basicContainer
   .get();
 
   //check wether a serie exists
-const hasSeries = measurements // eslint-disable-line no-unused-vars
+const hasSeries = basicContainer // eslint-disable-line no-unused-vars
   .type("flow")
   .variant("measured")
   .exists();                // true if any position exists
 
-const hasUpstreamValues = measurements // eslint-disable-line no-unused-vars
+const hasUpstreamValues = basicContainer // eslint-disable-line no-unused-vars
   .type("flow")
   .variant("measured")
   .exists({ position: POSITIONS.UPSTREAM, requireValues: true });
 
 // Passing everything explicitly
-const hasPercent = measurements.exists({ // eslint-disable-line no-unused-vars
+const hasPercent = basicContainer.exists({ // eslint-disable-line no-unused-vars
   type: "volume",
   variant: "percent",
   position: POSITIONS.AT_EQUIPMENT,
@@ -277,14 +277,14 @@ console.log(`  History: [${allValues.values.join(', ')}]\n`);
 
 console.log('--- Lagged sample comparison ---');
 
-const latest = stats.getCurrentValue();               // existing helper
-const prevSample = stats.getLaggedValue(1);           // new helper
-const prevPrevSample = stats.getLaggedValue(2);       // optional
+const latestSample = stats.getLaggedSample(0);   // newest sample object
+const prevSample = stats.getLaggedSample(1);
+const prevPrevSample = stats.getLaggedSample(2);
 
 if (prevSample) {
-  const delta = latest - prevSample.value;
+  const delta = (latestSample?.value ?? 0) - (prevSample.value ?? 0);
   console.log(
-    `Current vs previous: ${latest} ${statsData.unit} (t=${stats.get().getLatestTimestamp()}) vs ` +
+    `Current vs previous: ${latestSample?.value} ${statsData.unit} (t=${latestSample?.timestamp}) vs ` +
     `${prevSample.value} ${prevSample.unit} (t=${prevSample.timestamp})`
   );
   console.log(`Δ = ${delta.toFixed(2)} ${statsData.unit}`);
@@ -348,6 +348,68 @@ basicContainer.getTypes().forEach(type => {
   }
 });
 
+// ---------------------------------------------------------------------------
+// --- Child Aggregation -----------------------------------------------------
+// ---------------------------------------------------------------------------
+
+// ====================================
+// AGGREGATION WITH CHILD SERIES (sum)
+// ====================================
+console.log();
+console.log('--- Example X: Aggregation with sum() and child series ---');
+
+// Container where flow is stored internally in m3/h
+const aggContainer = new MeasurementContainer({
+  windowSize: 10,
+  defaultUnits: {
+    flow: 'm3/h',
+  },
+});
+
+// Two pumps both feeding the same inlet position
+aggContainer
+  .child('pumpA')
+  .type('flow')
+  .variant('measured')
+  .position('inlet')
+  .value(10, Date.now(), 'm3/h'); // 10 m3/h
+
+aggContainer
+  .child('pumpB')
+  .type('flow')
+  .variant('measured')
+  .position('inlet')
+  .value(15, Date.now(), 'm3/h'); // 15 m3/h
+
+// Another position, e.g. outlet, also with two pumps
+aggContainer
+  .child('pumpA')
+  .type('flow')
+  .variant('measured')
+  .position('outlet')
+  .value(8, Date.now(), 'm3/h'); // 8 m3/h
+
+aggContainer
+  .child('pumpB')
+  .type('flow')
+  .variant('measured')
+  .position('outlet')
+  .value(11, Date.now(), 'm3/h'); // 11 m3/h
+
+
+// 1) Sum only inlet position (children pumpA + pumpB)
+const inletTotal = aggContainer.sum('flow', 'measured', ['inlet']);
+console.log(`Total inlet flow: ${inletTotal} m3/h (expected 25 m3/h)`);
+
+// 2) Sum inlet + outlet positions together
+const totalAll = aggContainer.sum('flow', 'measured', ['inlet', 'outlet']);
+console.log(`Total inlet+outlet flow: ${totalAll} m3/h (expected 44 m3/h)`);
+
+// 3) Same sum but explicitly ask for a target unit (e.g. l/s)
+//    This will use convertModule(...) internally.
+//    If conversion is not supported, it will fall back to the raw value.
+const totalAllLps = aggContainer.sum('flow', 'measured', ['inlet', 'outlet'], 'l/s');
+console.log(`Total inlet+outlet flow in l/s: ${totalAllLps} l/s (converted from m3/h)\n`);
 
 
 console.log('\n✅ All examples complete!\n');

src/menu/aquonSamples.js

@@ -0,0 +1,30 @@
+'use strict';
+
+// AquonSamplesMenu is now a thin facade over assetResolver.
+// Backed by namespaces `monsterSamples` (sample codes, indexed by code)
+// and `monsterSpecs` (sampling defaults + per-sample overrides).
+
+const { assetResolver } = require('../registry');
+
+class AquonSamplesMenu {
+    // relPath retained for signature compatibility with the previous on-disk
+    // implementation; unused — the registry owns file locations.
+    constructor(/* relPath */) {}
+
+    getAllMenuData() {
+        const samples = assetResolver
+            .list('monsterSamples')
+            .map((id) => assetResolver.resolve('monsterSamples', id))
+            .filter(Boolean);
+        const specs = assetResolver.resolve('monsterSpecs', 'all') || { defaults: {}, bySample: {} };
+        return {
+            samples,
+            specs: {
+                defaults: specs.defaults || {},
+                bySample: specs.bySample || {},
+            },
+        };
+    }
+}
+
+module.exports = AquonSamplesMenu;

src/menu/iconHelpers.js

@@ -0,0 +1,359 @@
+'use strict';
+
+// iconHelpers.js — shared visual layer for EVOLV editor menus.
+//
+// The other menu modules (logger, physicalPosition, …) render their HTML
+// as plain Node-RED form rows with native <select>/<input> controls. This
+// module emits a single client-side helper bundle (`window.EVOLV.iconHelpers`)
+// that those menus call from their `initVisuals(node)` step to upgrade the
+// native controls in-place to icon cards.
+//
+// The native controls stay in the DOM (hidden) so Node-RED's load/save
+// path is untouched — clicks on the cards mirror back into the original
+// <select>/<input>.
+
+class IconHelpers {
+  static getClientInitCode() {
+    // Single IIFE so multiple menus on the same editor session share one
+    // copy of the helpers + one <style> tag.
+    return `
+      window.EVOLV = window.EVOLV || {};
+      if (!window.EVOLV.iconHelpers) {
+        window.EVOLV.iconHelpers = (function () {
+          const BLUE = '#1F4E79';
+          const STEEL = '#607484';
+          const UNIT = '#50a8d9';
+          const RED = '#B03A2E';
+          const AMBER = '#B7791F';
+
+          // ---- CSS (injected once) -----------------------------------
+          const CSS_ID = 'evolv-icon-pickers-css';
+          if (!document.getElementById(CSS_ID)) {
+            const style = document.createElement('style');
+            style.id = CSS_ID;
+            style.textContent = [
+              '.evolv-icon-picker { display:flex; gap:6px; flex-wrap:wrap; margin:6px 0 8px 0; }',
+              '.evolv-icon-option {',
+              '  width:72px; height:72px; box-sizing:border-box;',
+              '  border:2px solid #d0d0d0; border-radius:4px; background:#fafafa;',
+              '  padding:4px; cursor:pointer; user-select:none;',
+              '  display:flex; flex-direction:column; align-items:center; justify-content:center; gap:2px;',
+              '  transition:border-color 80ms ease-out, background 80ms ease-out, opacity 80ms ease-out;',
+              '}',
+              '.evolv-icon-option:hover { border-color:#86bbdd; background:#f5fafd; }',
+              '.evolv-icon-option:focus { outline:2px solid #1F4E79; outline-offset:2px; }',
+              '.evolv-icon-option-on { border-color:#50a8d9; background:#eaf4fb; }',
+              '.evolv-icon-glyph { width:100%; height:46px; display:flex; align-items:center; justify-content:center; }',
+              '.evolv-icon-option svg { width:100%; height:100%; display:block; }',
+              '.evolv-icon-label { font-size:10px; line-height:1; font-weight:600; color:#333; white-space:nowrap; letter-spacing:0; }',
+              '.evolv-icon-option:not(.evolv-icon-option-on) .evolv-icon-label { color:#888; }',
+              '.evolv-icon-option-on .evolv-off-cross { display:none; }',
+              '.evolv-native-hidden { position:absolute !important; opacity:0 !important; width:1px !important; height:1px !important; pointer-events:none !important; }',
+              '.evolv-native-row-compact label { display:none; }',
+              '.evolv-compact-row { display:flex; align-items:center; gap:8px; flex-wrap:wrap; margin:6px 0 8px 0; }',
+              '.evolv-log-toggle:not(.evolv-icon-option-on) svg .evolv-log-symbol,',
+              '.evolv-distance-toggle:not(.evolv-icon-option-on) svg .evolv-ruler-body { opacity:0.45; filter:grayscale(1); }',
+            ].join('\\n');
+            document.head.appendChild(style);
+          }
+
+          // ---- SVG library (inline, no external assets) --------------
+          const SVG = {
+            error: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <rect x="18" y="11" width="44" height="36" rx="3" fill="#fff" stroke="\${STEEL}" stroke-width="2.4"/>
+                <circle cx="40" cy="29" r="13" fill="#fff" stroke="\${RED}" stroke-width="3"/>
+                <line x1="34" y1="23" x2="46" y2="35" stroke="\${RED}" stroke-width="3.4" stroke-linecap="round"/>
+                <line x1="46" y1="23" x2="34" y2="35" stroke="\${RED}" stroke-width="3.4" stroke-linecap="round"/>
+              </svg>\`,
+            warn: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <rect x="18" y="11" width="44" height="36" rx="3" fill="#fff" stroke="\${STEEL}" stroke-width="2.4"/>
+                <path d="M40 17 L54 41 H26 Z" fill="#fff" stroke="\${AMBER}" stroke-width="3" stroke-linejoin="round"/>
+                <line x1="40" y1="25" x2="40" y2="33" stroke="\${AMBER}" stroke-width="3" stroke-linecap="round"/>
+                <circle cx="40" cy="38" r="2.2" fill="\${AMBER}"/>
+              </svg>\`,
+            info: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <rect x="18" y="11" width="44" height="36" rx="3" fill="#fff" stroke="\${STEEL}" stroke-width="2.4"/>
+                <circle cx="40" cy="29" r="13" fill="#fff" stroke="\${BLUE}" stroke-width="3"/>
+                <line x1="40" y1="28" x2="40" y2="37" stroke="\${BLUE}" stroke-width="3.2" stroke-linecap="round"/>
+                <circle cx="40" cy="22" r="2.4" fill="\${BLUE}"/>
+              </svg>\`,
+            debug: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <rect x="13" y="12" width="54" height="34" rx="3" fill="#fff" stroke="\${STEEL}" stroke-width="2.4"/>
+                <path d="M20 34 H29 L33 24 L40 39 L46 29 H59" fill="none" stroke="\${BLUE}" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+                <circle cx="59" cy="29" r="3" fill="\${UNIT}" stroke="#fff" stroke-width="1"/>
+              </svg>\`,
+            logToggle: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <g class="evolv-log-symbol">
+                  <rect x="10" y="10" width="60" height="38" rx="3" fill="#1F2933" stroke="\${STEEL}" stroke-width="2.4"/>
+                  <path d="M18 22 L26 29 L18 36" fill="none" stroke="#7ED957" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+                  <line x1="30" y1="38" x2="50" y2="38" stroke="#7ED957" stroke-width="2.6" stroke-linecap="round"/>
+                </g>
+                <g class="evolv-off-cross" stroke="\${RED}" stroke-width="4.5" stroke-linecap="round">
+                  <line x1="14" y1="12" x2="66" y2="46"/>
+                </g>
+              </svg>\`,
+            // Position icons — depict the PARENT equipment (pump volute +
+            // motor stub) plus a sensor marker located in the suction pipe
+            // (upstream), atop the equipment (atEquipment), or in the
+            // discharge pipe (downstream). Flow direction: left → right.
+            upstream: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <!-- suction pipe + flow arrow -->
+                <rect x="2" y="26" width="40" height="10" fill="#dde7f0" stroke="\${BLUE}" stroke-width="1.6"/>
+                <line x1="6" y1="31" x2="34" y2="31" stroke="\${BLUE}" stroke-width="1.6"/>
+                <polygon points="32,27 32,35 39,31" fill="\${BLUE}"/>
+                <!-- sensor marker on suction pipe -->
+                <line x1="20" y1="14" x2="20" y2="26" stroke="\${RED}" stroke-width="1.8"/>
+                <circle cx="20" cy="11" r="5" fill="#fff" stroke="\${RED}" stroke-width="2"/>
+                <circle cx="20" cy="11" r="1.6" fill="\${RED}"/>
+                <!-- pump (volute) + impeller hint + motor stub -->
+                <circle cx="60" cy="31" r="13" fill="#fff" stroke="\${STEEL}" stroke-width="2"/>
+                <path d="M 60 22 Q 68 26 68 31 Q 68 36 60 40 Q 52 36 52 31 Q 52 26 60 22" fill="none" stroke="#86bbdd" stroke-width="1.3"/>
+                <rect x="55" y="13" width="10" height="6" fill="\${STEEL}" stroke="#333" stroke-width="0.8"/>
+              </svg>\`,
+            atEquipment: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <!-- inlet stub -->
+                <rect x="2" y="26" width="22" height="10" fill="#dde7f0" stroke="\${BLUE}" stroke-width="1.6"/>
+                <line x1="4" y1="31" x2="20" y2="31" stroke="\${BLUE}" stroke-width="1.6"/>
+                <polygon points="18,27 18,35 24,31" fill="\${BLUE}"/>
+                <!-- outlet stub -->
+                <rect x="56" y="26" width="22" height="10" fill="#dde7f0" stroke="\${BLUE}" stroke-width="1.6"/>
+                <line x1="58" y1="31" x2="74" y2="31" stroke="\${BLUE}" stroke-width="1.6"/>
+                <polygon points="72,27 72,35 78,31" fill="\${BLUE}"/>
+                <!-- pump (volute) + impeller hint -->
+                <circle cx="40" cy="31" r="13" fill="#fff" stroke="\${STEEL}" stroke-width="2"/>
+                <path d="M 40 22 Q 48 26 48 31 Q 48 36 40 40 Q 32 36 32 31 Q 32 26 40 22" fill="none" stroke="#86bbdd" stroke-width="1.3"/>
+                <!-- sensor marker AT equipment (top, on the volute itself) -->
+                <line x1="40" y1="6"  x2="40" y2="18" stroke="\${RED}" stroke-width="1.8"/>
+                <circle cx="40" cy="6" r="5" fill="#fff" stroke="\${RED}" stroke-width="2"/>
+                <circle cx="40" cy="6" r="1.6" fill="\${RED}"/>
+              </svg>\`,
+            downstream: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <!-- pump (volute) + impeller hint + motor stub -->
+                <circle cx="20" cy="31" r="13" fill="#fff" stroke="\${STEEL}" stroke-width="2"/>
+                <path d="M 20 22 Q 28 26 28 31 Q 28 36 20 40 Q 12 36 12 31 Q 12 26 20 22" fill="none" stroke="#86bbdd" stroke-width="1.3"/>
+                <rect x="15" y="13" width="10" height="6" fill="\${STEEL}" stroke="#333" stroke-width="0.8"/>
+                <!-- discharge pipe + flow arrow -->
+                <rect x="38" y="26" width="40" height="10" fill="#dde7f0" stroke="\${BLUE}" stroke-width="1.6"/>
+                <line x1="42" y1="31" x2="70" y2="31" stroke="\${BLUE}" stroke-width="1.6"/>
+                <polygon points="68,27 68,35 75,31" fill="\${BLUE}"/>
+                <!-- sensor marker on discharge pipe -->
+                <line x1="60" y1="14" x2="60" y2="26" stroke="\${RED}" stroke-width="1.8"/>
+                <circle cx="60" cy="11" r="5" fill="#fff" stroke="\${RED}" stroke-width="2"/>
+                <circle cx="60" cy="11" r="1.6" fill="\${RED}"/>
+              </svg>\`,
+            // Output-format icons — used by the shared
+            // renderOutputFormatPicker helper so every node renders the
+            // process/json/csv/influxdb dropdowns with the same visuals.
+            outputProcess: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <rect x="10" y="14" width="20" height="30" rx="2" fill="#f7fafc" stroke="\${STEEL}" stroke-width="2.4"/>
+                <rect x="50" y="14" width="20" height="30" rx="2" fill="#f7fafc" stroke="\${STEEL}" stroke-width="2.4"/>
+                <line x1="30" y1="29" x2="46" y2="29" stroke="\${BLUE}" stroke-width="3" stroke-linecap="round"/>
+                <path d="M42 24 L48 29 L42 34" fill="none" stroke="\${BLUE}" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+              </svg>\`,
+            outputJson: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <g fill="none" stroke="\${BLUE}" stroke-width="3.4" stroke-linecap="round" stroke-linejoin="round">
+                  <path d="M30 14 C22 16 22 26 27 29 C22 32 22 42 30 44"/>
+                  <path d="M50 14 C58 16 58 26 53 29 C58 32 58 42 50 44"/>
+                </g>
+                <g fill="\${STEEL}">
+                  <circle cx="36" cy="29" r="2.2"/>
+                  <circle cx="44" cy="29" r="2.2"/>
+                </g>
+              </svg>\`,
+            outputCsv: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <rect x="12" y="12" width="56" height="34" rx="2" fill="#fff" stroke="\${STEEL}" stroke-width="2.4"/>
+                <line x1="12" y1="22" x2="68" y2="22" stroke="\${STEEL}" stroke-width="2"/>
+                <g stroke="\${STEEL}" stroke-width="1.6">
+                  <line x1="12" y1="34" x2="68" y2="34"/>
+                  <line x1="31" y1="12" x2="31" y2="46"/>
+                  <line x1="49" y1="12" x2="49" y2="46"/>
+                </g>
+              </svg>\`,
+            outputInflux: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <ellipse cx="40" cy="15" rx="22" ry="6" fill="#f7fafc" stroke="\${STEEL}" stroke-width="2.4"/>
+                <path d="M18 15 V42 C18 46 28 49 40 49 C52 49 62 46 62 42 V15" fill="#f7fafc" stroke="\${STEEL}" stroke-width="2.4"/>
+                <path d="M18 28 C26 32 54 32 62 28" fill="none" stroke="\${STEEL}" stroke-width="1.6" opacity="0.6"/>
+                <path d="M22 39 L30 32 L38 41 L46 34 L54 38" fill="none" stroke="\${BLUE}" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+              </svg>\`,
+            distance: \`
+              <svg viewBox="0 0 80 58" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+                <g class="evolv-ruler-body">
+                  <rect x="12" y="22" width="56" height="14" rx="1.5" fill="#fff" stroke="\${STEEL}" stroke-width="2.4"/>
+                  <g stroke="\${STEEL}" stroke-width="1.8" stroke-linecap="round">
+                    <line x1="20" y1="22" x2="20" y2="30"/>
+                    <line x1="28" y1="22" x2="28" y2="27"/>
+                    <line x1="36" y1="22" x2="36" y2="30"/>
+                    <line x1="44" y1="22" x2="44" y2="27"/>
+                    <line x1="52" y1="22" x2="52" y2="30"/>
+                    <line x1="60" y1="22" x2="60" y2="27"/>
+                  </g>
+                </g>
+                <g class="evolv-off-cross" stroke="\${RED}" stroke-width="4.5" stroke-linecap="round">
+                  <line x1="16" y1="14" x2="64" y2="46"/>
+                </g>
+              </svg>\`,
+          };
+
+          // ---- Helpers -----------------------------------------------
+          function dispatchChange(el) {
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+          }
+
+          // renderSelectPicker: replace a native <select> with a row of
+          // icon cards. labels object maps option.value → display string.
+          function renderSelectPicker(select, holder, icons, labels) {
+            if (!select || !holder || holder.dataset.evolvReady === '1') return;
+            holder.dataset.evolvReady = '1';
+            select.classList.add('evolv-native-hidden');
+
+            const options = Array.from(select.options).map((option) => ({
+              value: option.value,
+              title: option.textContent || option.value,
+              label: (labels && labels[option.value]) || option.textContent || option.value,
+              svg: icons[option.value],
+            })).filter((option) => option.svg);
+
+            holder.innerHTML = options.map((option) => (
+              '<div class="evolv-icon-option" data-value="' + option.value + '" role="radio" tabindex="0"' +
+              ' aria-label="' + option.title + '" aria-checked="false" title="' + option.title + '">' +
+              '  <div class="evolv-icon-glyph">' + option.svg + '</div>' +
+              '  <div class="evolv-icon-label">' + option.label + '</div>' +
+              '</div>'
+            )).join('');
+
+            const buttons = Array.from(holder.querySelectorAll('.evolv-icon-option'));
+            function sync() {
+              const current = select.value || (options[0] && options[0].value) || '';
+              for (const button of buttons) {
+                const on = button.getAttribute('data-value') === current;
+                button.classList.toggle('evolv-icon-option-on', on);
+                button.setAttribute('aria-checked', String(on));
+              }
+            }
+            function pick(value) {
+              select.value = value;
+              dispatchChange(select);
+              sync();
+            }
+            for (const button of buttons) {
+              button.addEventListener('click', () => pick(button.getAttribute('data-value')));
+              button.addEventListener('keydown', (event) => {
+                if (event.key === ' ' || event.key === 'Enter') {
+                  event.preventDefault();
+                  pick(button.getAttribute('data-value'));
+                }
+              });
+            }
+            select.addEventListener('change', sync);
+            sync();
+          }
+
+          // renderToggle: replace a checkbox with a single icon card whose
+          // label flips between {on, off}. Passing a string for label
+          // uses the same string for both states.
+          function renderToggle(checkbox, holder, svg, label) {
+            if (!checkbox || !holder || holder.dataset.evolvReady === '1') return;
+            holder.dataset.evolvReady = '1';
+            checkbox.classList.add('evolv-native-hidden');
+            const labels = typeof label === 'string' ? { on: label, off: label } : label;
+            holder.innerHTML =
+              '<div class="evolv-icon-glyph">' + svg + '</div>' +
+              '<div class="evolv-icon-label">' + labels.off + '</div>';
+            const labelEl = holder.querySelector('.evolv-icon-label');
+
+            function sync() {
+              const on = checkbox.checked;
+              holder.classList.toggle('evolv-icon-option-on', on);
+              holder.setAttribute('aria-checked', String(on));
+              if (labelEl) labelEl.textContent = on ? labels.on : labels.off;
+            }
+            function toggle() {
+              checkbox.checked = !checkbox.checked;
+              dispatchChange(checkbox);
+              sync();
+            }
+            holder.addEventListener('click', toggle);
+            holder.addEventListener('keydown', (event) => {
+              if (event.key === ' ' || event.key === 'Enter') {
+                event.preventDefault();
+                toggle();
+              }
+            });
+            checkbox.addEventListener('change', sync);
+            sync();
+          }
+
+          // renderOutputFormatPicker: shared widget for the process &
+          // dbase output-format <select>s carried by most EVOLV nodes.
+          // Encapsulates the icon set + labels so every node renders the
+          // same visuals. Pass the native <select> and an empty holder
+          // <div class="evolv-icon-picker">.
+          const OUTPUT_FORMAT_ICONS = {
+            process:  SVG.outputProcess,
+            json:     SVG.outputJson,
+            csv:      SVG.outputCsv,
+            influxdb: SVG.outputInflux,
+          };
+          const OUTPUT_FORMAT_LABELS = {
+            process:  'Process',
+            json:     'JSON',
+            csv:      'CSV',
+            influxdb: 'Influx',
+          };
+          function renderOutputFormatPicker(select, holder) {
+            renderSelectPicker(select, holder, OUTPUT_FORMAT_ICONS, OUTPUT_FORMAT_LABELS);
+          }
+
+          // upgradeOutputFormatSelects: idempotent platform-wide upgrade.
+          // Scans the open editor dialog for the two canonical output-format
+          // selects and replaces each with the icon picker. Skips selects
+          // that are already upgraded (class evolv-native-hidden) or that
+          // already have a sibling picker placed by the node's HTML.
+          // Called from MenuManager's initEditor wrapper so every node
+          // inherits the picker without per-node template edits.
+          function upgradeOutputFormatSelects() {
+            const specs = [
+              { id: 'node-input-processOutputFormat', aria: 'Process output format' },
+              { id: 'node-input-dbaseOutputFormat',   aria: 'Database output format' }
+            ];
+            specs.forEach((spec) => {
+              const select = document.getElementById(spec.id);
+              if (!select) return;
+              if (select.classList && select.classList.contains('evolv-native-hidden')) return;
+              const parent = select.parentNode;
+              if (!parent) return;
+              // Skip if a sibling picker already exists (manual wiring).
+              const siblings = parent.children || [];
+              for (let i = 0; i < siblings.length; i += 1) {
+                const sib = siblings[i];
+                if (sib !== select && sib.classList && sib.classList.contains('evolv-icon-picker')) return;
+              }
+              const holder = document.createElement('div');
+              holder.className = 'evolv-icon-picker';
+              holder.setAttribute('role', 'radiogroup');
+              holder.setAttribute('aria-label', spec.aria);
+              parent.appendChild(holder);
+              renderOutputFormatPicker(select, holder);
+            });
+          }
+
+          return { SVG, renderSelectPicker, renderToggle, renderOutputFormatPicker, upgradeOutputFormatSelects };
+        })();
+      }
+    `;
+  }
+}
+
+module.exports = IconHelpers;

src/menu/index.js

@@ -2,16 +2,23 @@ const AssetMenu = require('./asset.js');
 // TagcodeApp and DynamicAssetMenu available via ./tagcodeApp.js
 const LoggerMenu = require('./logger.js');
 const PhysicalPositionMenu = require('./physicalPosition.js');
+const AquonSamplesMenu = require('./aquonSamples.js');
+const IconHelpers = require('./iconHelpers.js');
+const ConfigManager = require('../configs');
 
 class MenuManager {
 
     constructor() {
         this.registeredMenus = new Map();
+        this.configManager = new ConfigManager('../configs');
         // Register factory functions
-        this.registerMenu('asset', () => new AssetMenu()); // static menu to be replaced by dynamic one but later
+        this.registerMenu('asset', (nodeName) => new AssetMenu({
+            softwareType: this._getSoftwareType(nodeName)
+        })); // static menu to be replaced by dynamic one but later
         //this.registerMenu('asset', (nodeName) => new DynamicAssetMenu(nodeName, new TagcodeApp()));
         this.registerMenu('logger', () => new LoggerMenu());
         this.registerMenu('position', () => new PhysicalPositionMenu());
+        this.registerMenu('aquon', () => new AquonSamplesMenu());
     }
 
     /**
@@ -23,6 +30,34 @@ class MenuManager {
         this.registeredMenus.set(menuType, menuFactory);
     }
 
+    _getSoftwareType(nodeName) {
+        if (!nodeName) {
+            return null;
+        }
+
+        try {
+            const config = this.configManager.getConfig(nodeName);
+            const softwareType = config?.functionality?.softwareType;
+
+            if (typeof softwareType === 'string' && softwareType.trim()) {
+                return softwareType;
+            }
+            if (
+                softwareType &&
+                typeof softwareType === 'object' &&
+                typeof softwareType.default === 'string' &&
+                softwareType.default.trim()
+            ) {
+                return softwareType.default;
+            }
+
+            return nodeName;
+        } catch (error) {
+            console.warn(`Unable to determine softwareType for ${nodeName}: ${error.message}`);
+            return nodeName;
+        }
+    }
+
     /**
      * Create a complete endpoint script with data and initialization functions
      * @param {string} nodeName - The name of the node type
@@ -54,7 +89,7 @@ class MenuManager {
                 try {
                     const handler = instantiatedMenus.get(menuType);
                     if (handler && typeof handler.getAllMenuData === 'function') {
-                        menuData[menuType] = handler.getAllMenuData();
+                        menuData[menuType] = handler.getAllMenuData(nodeName);
                     } else {
                         // Provide default empty data if method doesn't exist
                         menuData[menuType] = {};
@@ -104,6 +139,9 @@ class MenuManager {
                 window.EVOLV.nodes = window.EVOLV.nodes || {};
                 window.EVOLV.nodes.${nodeName} = window.EVOLV.nodes.${nodeName} || {};
 
+                // Shared icon-picker helpers (no-op if already loaded by another node)
+                ${IconHelpers.getClientInitCode()}
+
                 // Initialize menu namespaces
                 ${menuTypes.map(type => `window.EVOLV.nodes.${nodeName}.${type}Menu = window.EVOLV.nodes.${nodeName}.${type}Menu || {};`).join('\n                ')}
 
@@ -129,12 +167,26 @@ class MenuManager {
                     try {
                         ${menuTypes.map(type => `
                         try {
+                            // initEditor is responsible for calling initVisuals
+                            // at the right time (after any async data load).
                             if (window.EVOLV.nodes.${nodeName}.${type}Menu && window.EVOLV.nodes.${nodeName}.${type}Menu.initEditor) {
                                 window.EVOLV.nodes.${nodeName}.${type}Menu.initEditor(node);
                             }
                         } catch (${type}Error) {
                             console.error('Error initializing ${type} menu for ${nodeName}:', ${type}Error);
                         }`).join('')}
+
+                        // Platform-wide: upgrade output-format <select>s
+                        // (process/dbase) to icon pickers. Idempotent — no-op
+                        // for nodes whose HTML already wires the picker, and
+                        // skips when the selects aren't present.
+                        try {
+                            if (window.EVOLV && window.EVOLV.iconHelpers && window.EVOLV.iconHelpers.upgradeOutputFormatSelects) {
+                                window.EVOLV.iconHelpers.upgradeOutputFormatSelects();
+                            }
+                        } catch (outputUpgradeError) {
+                            console.error('Error upgrading output-format selects for ${nodeName}:', outputUpgradeError);
+                        }
                     } catch (editorError) {
                         console.error('Error in main editor initialization for ${nodeName}:', editorError);
                     }
@@ -172,4 +224,4 @@ class MenuManager {
     }
 }
 
-module.exports = MenuManager;
+module.exports = MenuManager;

src/menu/logger.js

@@ -103,12 +103,68 @@ getHtmlInjectionCode(nodeName) {
     `;
   }
 
-  // 5) Compose everything into one client‐side payload
+  // 5) Client-side: upgrade native controls to icon cards.
+  //
+  // Runs after wireEvents (which has already hooked the checkbox + select).
+  // Adds a small toggle card next to the native checkbox and a 4-icon
+  // picker row next to the native select; the natives are then hidden.
+  getVisualInjectionCode(nodeName) {
+    return `
+      // Logger visual upgrade for ${nodeName}
+      window.EVOLV.nodes.${nodeName}.loggerMenu.initVisuals = function(node) {
+        const helpers = window.EVOLV && window.EVOLV.iconHelpers;
+        if (!helpers) return;
+
+        // --- Log toggle (replaces native checkbox + label) ----------
+        const checkbox = document.getElementById('node-input-enableLog');
+        if (checkbox) {
+          const row = checkbox.closest('.form-row');
+          if (row && !document.getElementById('evolv-log-toggle-' + node.id)) {
+            row.classList.add('evolv-native-row-compact');
+            const holder = document.createElement('div');
+            holder.id = 'evolv-log-toggle-' + node.id;
+            holder.className = 'evolv-icon-option evolv-log-toggle';
+            holder.setAttribute('role', 'switch');
+            holder.setAttribute('tabindex', '0');
+            holder.setAttribute('aria-label', 'Logging');
+            holder.setAttribute('aria-checked', 'false');
+            holder.setAttribute('title', 'Logging');
+            row.appendChild(holder);
+            helpers.renderToggle(checkbox, holder, helpers.SVG.logToggle, { on: 'Log', off: 'Off' });
+          }
+        }
+
+        // --- Log-level picker (replaces native select) --------------
+        const select = document.getElementById('node-input-logLevel');
+        if (select) {
+          const row = document.getElementById('row-logLevel');
+          if (row && !document.getElementById('evolv-log-level-picker-' + node.id)) {
+            row.classList.add('evolv-native-row-compact');
+            const holder = document.createElement('div');
+            holder.id = 'evolv-log-level-picker-' + node.id;
+            holder.className = 'evolv-icon-picker';
+            holder.setAttribute('role', 'radiogroup');
+            holder.setAttribute('aria-label', 'Log level');
+            row.appendChild(holder);
+            helpers.renderSelectPicker(
+              select,
+              holder,
+              { error: helpers.SVG.error, warn: helpers.SVG.warn, info: helpers.SVG.info, debug: helpers.SVG.debug },
+              { error: 'Error', warn: 'Warn', info: 'Info', debug: 'Debug' }
+            );
+          }
+        }
+      };
+    `;
+  }
+
+  // 6) Compose everything into one client‐side payload
   getClientInitCode(nodeName) {
-    const dataCode   = this.getDataInjectionCode(nodeName);
-    const eventCode  = this.getEventInjectionCode(nodeName);
-    const saveCode   = this.getSaveInjectionCode(nodeName);
-    const htmlCode  = this.getHtmlInjectionCode(nodeName);
+    const dataCode    = this.getDataInjectionCode(nodeName);
+    const eventCode   = this.getEventInjectionCode(nodeName);
+    const saveCode    = this.getSaveInjectionCode(nodeName);
+    const htmlCode    = this.getHtmlInjectionCode(nodeName);
+    const visualCode  = this.getVisualInjectionCode(nodeName);
 
     return `
       // --- LoggerMenu for ${nodeName} ---
@@ -119,13 +175,16 @@ getHtmlInjectionCode(nodeName) {
       ${dataCode}
       ${eventCode}
       ${saveCode}
+      ${visualCode}
 
-      // oneditprepare calls this
+      // oneditprepare calls this. Visual upgrade runs last so the natives
+      // are already populated + wired.
       window.EVOLV.nodes.${nodeName}.loggerMenu.initEditor = function(node) {
       // ------------------  BELOW sequence is important! -------------------------------
         this.injectHtml();
         this.loadData(node);
         this.wireEvents(node);
+        if (this.initVisuals) this.initVisuals(node);
       };
     `;
   }

src/menu/physicalPosition.js

@@ -6,9 +6,9 @@ class PhysicalPositionMenu {
     return {
       positionGroups: [
         { group: 'Positional', options: [
-            { value: 'upstream',     label: '← Upstream', icon: '←'},
+            { value: 'upstream',     label: '→ Upstream', icon: '→'}, //flow is then typically left to right
             { value: 'atEquipment',  label: '⊥ in place' , icon: '⊥' },
-            { value: 'downstream',   label: '→ Downstream' , icon: '→' }
+            { value: 'downstream',   label: '← Downstream' , icon: '←' }
           ]
         }
       ],
@@ -245,12 +245,69 @@ getSaveInjectionCode(nodeName) {
   `;
 }
 
-  // 7) Compose everything into one client bundle
+  // 7) Client-side: upgrade native controls to icon cards.
+  //
+  // Runs after wireEvents. Wraps the position <select> with a 3-card row
+  // (upstream / atEquipment / downstream) and the hasDistance checkbox
+  // with a single toggle card. The native controls are hidden but stay
+  // in the DOM as save targets.
+  getVisualInjectionCode(nodeName) {
+    return `
+      // PhysicalPosition visual upgrade for ${nodeName}
+      window.EVOLV.nodes.${nodeName}.positionMenu.initVisuals = function(node) {
+        const helpers = window.EVOLV && window.EVOLV.iconHelpers;
+        if (!helpers) return;
+
+        // --- Position picker (replaces native <select>) -------------
+        const select = document.getElementById('node-input-positionVsParent');
+        if (select) {
+          const row = select.closest('.form-row');
+          if (row && !document.getElementById('evolv-position-picker-' + node.id)) {
+            row.classList.add('evolv-native-row-compact');
+            const holder = document.createElement('div');
+            holder.id = 'evolv-position-picker-' + node.id;
+            holder.className = 'evolv-icon-picker';
+            holder.setAttribute('role', 'radiogroup');
+            holder.setAttribute('aria-label', 'Physical position vs parent');
+            row.appendChild(holder);
+            helpers.renderSelectPicker(
+              select,
+              holder,
+              { upstream: helpers.SVG.upstream, atEquipment: helpers.SVG.atEquipment, downstream: helpers.SVG.downstream },
+              { upstream: 'Upstream', atEquipment: 'At', downstream: 'Downstream' }
+            );
+          }
+        }
+
+        // --- Distance toggle (replaces native checkbox) -------------
+        const checkbox = document.getElementById('node-input-hasDistance');
+        if (checkbox) {
+          const row = checkbox.closest('.form-row');
+          if (row && !document.getElementById('evolv-distance-toggle-' + node.id)) {
+            row.classList.add('evolv-native-row-compact');
+            const holder = document.createElement('div');
+            holder.id = 'evolv-distance-toggle-' + node.id;
+            holder.className = 'evolv-icon-option evolv-distance-toggle';
+            holder.setAttribute('role', 'switch');
+            holder.setAttribute('tabindex', '0');
+            holder.setAttribute('aria-label', 'Distance');
+            holder.setAttribute('aria-checked', 'false');
+            holder.setAttribute('title', 'Distance');
+            row.appendChild(holder);
+            helpers.renderToggle(checkbox, holder, helpers.SVG.distance, { on: 'Distance', off: 'Off' });
+          }
+        }
+      };
+    `;
+  }
+
+  // 8) Compose everything into one client bundle
   getClientInitCode(nodeName) {
-    const htmlCode   = this.getHtmlInjectionCode(nodeName);
-    const dataCode   = this.getDataInjectionCode(nodeName);
-    const eventCode  = this.getEventInjectionCode(nodeName);
-    const saveCode   = this.getSaveInjectionCode(nodeName);
+    const htmlCode    = this.getHtmlInjectionCode(nodeName);
+    const dataCode    = this.getDataInjectionCode(nodeName);
+    const eventCode   = this.getEventInjectionCode(nodeName);
+    const saveCode    = this.getSaveInjectionCode(nodeName);
+    const visualCode  = this.getVisualInjectionCode(nodeName);
 
     return `
       // --- PhysicalPositionMenu for ${nodeName} ---
@@ -261,12 +318,15 @@ getSaveInjectionCode(nodeName) {
       ${dataCode}
       ${eventCode}
       ${saveCode}
+      ${visualCode}
 
-      // hook into oneditprepare
+      // hook into oneditprepare. Visual upgrade runs last so the natives
+      // are already populated + wired.
       window.EVOLV.nodes.${nodeName}.positionMenu.initEditor = function(node) {
         this.injectHtml();
         this.loadData(node);
         this.wireEvents(node);
+        if (this.initVisuals) this.initVisuals(node);
       };
     `;
   }

src/nodered/BaseNodeAdapter.js

@@ -0,0 +1,213 @@
+/**
+ * BaseNodeAdapter — shared nodeClass scaffolding.
+ *
+ * Consolidates the boilerplate every node's nodeClass.js repeats today
+ * (config build → domain instantiate → registration delay → tick loop →
+ * status loop → input dispatch → close handler). Subclasses declare what
+ * varies (DomainClass, commands, output strategy) via static fields and
+ * override `buildDomainConfig(uiConfig, nodeId)` to produce the per-node
+ * config slice.
+ *
+ * See CONTRACTS.md §2; OPEN_QUESTIONS.md (event-driven default + tick
+ * fire-and-forget resolution, 2026-05-10).
+ */
+
+'use strict';
+
+const ConfigManager = require('../configs/index.js');
+const OutputUtils = require('../helper/outputUtils.js');
+const { createRegistry } = require('./commandRegistry.js');
+const { StatusUpdater } = require('./statusUpdater.js');
+const convert = require('../convert');
+
+const REGISTRATION_DELAY_MS = 100;
+
+function _buildImplicitUnitsCommand(getCommands, getNodeName) {
+    return {
+        topic: 'query.units',
+        payloadSchema: { type: 'any' },
+        description: 'Returns the unit spec (measure, default, accepted) for every topic that declares units.',
+        handler: (source, msg, ctx) => {
+            const units = {};
+            for (const d of getCommands()) {
+                if (!d.units) continue;
+                const accepted = (convert && typeof convert.possibilities === 'function')
+                    ? convert.possibilities(d.units.measure) : [];
+                units[d.topic] = {
+                    measure: d.units.measure,
+                    default: d.units.default,
+                    accepted,
+                };
+            }
+            const reply = Object.assign({}, msg, {
+                topic: 'query.units',
+                payload: { node: getNodeName(), units },
+            });
+            if (ctx && typeof ctx.send === 'function') ctx.send([reply, null, null]);
+        },
+    };
+}
+
+class BaseNodeAdapter {
+    constructor(uiConfig, RED, nodeInstance, nameOfNode) {
+        const ctor = this.constructor;
+        if (ctor === BaseNodeAdapter) {
+            throw new Error('BaseNodeAdapter is abstract; subclass it and declare static DomainClass + commands');
+        }
+        if (typeof ctor.DomainClass !== 'function') {
+            throw new Error(`${ctor.name}: static DomainClass is required (a class to instantiate)`);
+        }
+        if (!Array.isArray(ctor.commands)) {
+            throw new Error(`${ctor.name}: static commands is required (array of descriptors; use [] for none)`);
+        }
+        if (typeof this.buildDomainConfig !== 'function') {
+            throw new Error(`${ctor.name}: must implement buildDomainConfig(uiConfig, nodeId)`);
+        }
+
+        this.node = nodeInstance;
+        this.RED = RED;
+        this.name = nameOfNode;
+
+        const cfgMgr = new ConfigManager();
+        this.defaultConfig = cfgMgr.getConfig(this.name);
+        this.config = cfgMgr.buildConfig(
+            this.name,
+            uiConfig,
+            this.node.id,
+            this.buildDomainConfig(uiConfig, this.node.id) || {},
+        );
+
+        this.source = new ctor.DomainClass(this.config);
+        // Sibling-node lookup uses RED.nodes.getNode(id).source — see existing
+        // pumpingStation/measurement nodeClass _attachInputHandler patterns.
+        this.node.source = this.source;
+
+        // `static alwaysEmitFields = ['ctrl', …]` on a subclass exempts those
+        // fields from delta compression so they trace continuously downstream.
+        this._output = new OutputUtils({ alwaysEmit: ctor.alwaysEmitFields });
+        const userHasUnitsQuery = ctor.commands.some(
+            (c) => c && (c.topic === 'query.units' || (Array.isArray(c.aliases) && c.aliases.includes('query.units'))));
+        const mergedCommands = userHasUnitsQuery
+            ? ctor.commands
+            : ctor.commands.concat([_buildImplicitUnitsCommand(
+                () => this._commands.list(),
+                () => this.name,
+            )]);
+        this._commands = createRegistry(mergedCommands, { logger: this.source?.logger });
+
+        this._tickInterval = null;
+        this._outputChangedListener = null;
+        this._scheduleRegistration();
+        this._wireOutputs();
+
+        this._statusUpdater = new StatusUpdater({
+            node: this.node,
+            source: this.source,
+            intervalMs: ctor.statusInterval ?? 1000,
+            logger: this.source?.logger,
+        });
+        this._statusUpdater.start();
+
+        this._attachInputHandler();
+        this._attachCloseHandler();
+
+        if (typeof this.extraSetup === 'function') this.extraSetup();
+    }
+
+    _scheduleRegistration() {
+        // Delayed so siblings have finished constructing before the parent
+        // receives the registration message.
+        setTimeout(() => {
+            this.node.send([
+                null,
+                null,
+                {
+                    topic: 'child.register',
+                    payload: this.node.id,
+                    positionVsParent: this.config?.functionality?.positionVsParent ?? 'atEquipment',
+                    distance: this.config?.functionality?.distance ?? null,
+                },
+            ]);
+        }, REGISTRATION_DELAY_MS);
+    }
+
+    _wireOutputs() {
+        const ctor = this.constructor;
+        const interval = ctor.tickInterval;
+        if (typeof interval === 'number' && interval > 0) {
+            this._tickInterval = setInterval(() => {
+                // Fire-and-forget per OPEN_QUESTIONS 2026-05-10. Domain owns
+                // its own serialisation via LatestWinsGate when needed.
+                try { this.source.tick?.(); }
+                catch (err) { this.source?.logger?.error?.(`tick threw: ${err.message}`); }
+                this._emitOutputs();
+            }, interval);
+            return;
+        }
+        // Event-driven default: domain emits 'output-changed' when its
+        // public output state shifts; adapter pushes outputs in response.
+        const emitter = this.source?.emitter;
+        if (emitter && typeof emitter.on === 'function') {
+            this._outputChangedListener = () => this._emitOutputs();
+            emitter.on('output-changed', this._outputChangedListener);
+        }
+    }
+
+    _emitOutputs() {
+        if (typeof this.source.getOutput !== 'function') return;
+        const raw = this.source.getOutput();
+        const cfg = this.source.config || this.config;
+        const processMsg = this._output.formatMsg(raw, cfg, 'process');
+        const influxMsg = this._output.formatMsg(raw, cfg, 'influxdb');
+        this.node.send([processMsg, influxMsg, null]);
+    }
+
+    _attachInputHandler() {
+        this.node.on('input', async (msg, send, done) => {
+            try {
+                await this._commands.dispatch(msg, this.source, {
+                    node: this.node,
+                    RED: this.RED,
+                    send,
+                    logger: this.source?.logger,
+                });
+                if (typeof this.extraInputDispatch === 'function') {
+                    await this.extraInputDispatch(msg, send, done);
+                }
+            } catch (err) {
+                this.source?.logger?.error?.(err.message);
+            } finally {
+                if (typeof done === 'function') done();
+            }
+        });
+    }
+
+    _attachCloseHandler() {
+        this.node.on('close', (done) => {
+            try {
+                if (this._tickInterval) {
+                    clearInterval(this._tickInterval);
+                    this._tickInterval = null;
+                }
+                if (this._outputChangedListener && this.source?.emitter?.off) {
+                    this.source.emitter.off('output-changed', this._outputChangedListener);
+                    this._outputChangedListener = null;
+                }
+                this._statusUpdater?.stop();
+                this.source?.close?.();
+                if (typeof this.extraClose === 'function') this.extraClose();
+                try { this.node.status({}); } catch (_) { /* best effort */ }
+            } catch (err) {
+                this.source?.logger?.error?.(`close handler threw: ${err.message}`);
+            } finally {
+                if (typeof done === 'function') done();
+            }
+        });
+    }
+}
+
+// Defaults overridable via subclass static fields.
+BaseNodeAdapter.tickInterval = null;
+BaseNodeAdapter.statusInterval = 1000;
+
+module.exports = BaseNodeAdapter;

src/nodered/commandRegistry.js

@@ -0,0 +1,237 @@
+'use strict';
+
+// Declarative dispatch for a node's input topics. Each node declares its
+// commands as an array of descriptors; the registry builds an O(1) lookup
+// keyed by canonical topic + alias, validates the payload against a small
+// shape schema, and invokes the handler. Replaces the per-node ~100-line
+// `switch (msg.topic)` block in nodeClass._attachInputHandler.
+//
+// Lightweight on purpose: the schema is a typeof-check ladder, not full
+// JSON-Schema. Anything richer belongs in the handler itself, which has
+// access to logger via ctx.
+
+const convert = require('../convert');
+
+const SCALAR_TYPES = new Set(['string', 'number', 'boolean', 'object', 'any', 'none']);
+
+function _acceptedList(measure) {
+    if (convert && typeof convert.possibilities === 'function') {
+        const list = convert.possibilities(measure);
+        if (Array.isArray(list) && list.length) return list.join(', ');
+    }
+    return '(see convert docs)';
+}
+
+function _describeUnit(unit) {
+    try { return convert().describe(unit); } catch (_) { return null; }
+}
+
+function _extractValueAndUnit(msg) {
+    if (!msg || typeof msg !== 'object') return null;
+    const p = msg.payload;
+    if (typeof p === 'number') return { value: p, unit: msg.unit };
+    if (p && typeof p === 'object' && typeof p.value === 'number') {
+        return { value: p.value, unit: p.unit ?? msg.unit };
+    }
+    return null;
+}
+
+class CommandRegistry {
+    constructor(commands, options = {}) {
+        if (!Array.isArray(commands)) {
+            throw new TypeError('CommandRegistry requires an array of command descriptors');
+        }
+        this._logger = options.logger || null;
+        this._byKey = new Map();          // topic-or-alias -> descriptor
+        this._canonicalByAlias = new Map();
+        this._descriptors = [];
+        this._deprecationCounts = new Map();
+        this._deprecationLogged = new Set();
+        for (const cmd of commands) this._register(cmd);
+    }
+
+    _register(cmd) {
+        if (!cmd || typeof cmd.topic !== 'string' || cmd.topic.length === 0) {
+            throw new TypeError('command descriptor requires a non-empty string topic');
+        }
+        if (typeof cmd.handler !== 'function') {
+            throw new TypeError(`command '${cmd.topic}' requires a handler function`);
+        }
+        if (this._byKey.has(cmd.topic)) {
+            throw new Error(`duplicate command topic '${cmd.topic}'`);
+        }
+        const aliases = Array.isArray(cmd.aliases) ? cmd.aliases.slice() : [];
+        for (const alias of aliases) {
+            if (typeof alias !== 'string' || alias.length === 0) {
+                throw new TypeError(`command '${cmd.topic}' has an invalid alias`);
+            }
+            if (this._byKey.has(alias)) {
+                throw new Error(`alias '${alias}' for '${cmd.topic}' collides with existing topic or alias`);
+            }
+        }
+        const units = this._validateUnits(cmd);
+        const descriptor = {
+            topic: cmd.topic,
+            aliases,
+            payloadSchema: cmd.payloadSchema || null,
+            description: typeof cmd.description === 'string' ? cmd.description : null,
+            units,
+            handler: cmd.handler,
+        };
+        this._byKey.set(cmd.topic, descriptor);
+        for (const alias of aliases) {
+            this._byKey.set(alias, descriptor);
+            this._canonicalByAlias.set(alias, cmd.topic);
+        }
+        this._descriptors.push(descriptor);
+    }
+
+    _validateUnits(cmd) {
+        if (cmd.units === undefined || cmd.units === null) return null;
+        const { measure, default: def } = cmd.units;
+        if (typeof measure !== 'string' || measure.length === 0 ||
+            typeof def !== 'string' || def.length === 0) {
+            throw new TypeError(
+                `command '${cmd.topic}' units requires { measure: string, default: string }`);
+        }
+        return { measure, default: def };
+    }
+
+    has(topic) {
+        return typeof topic === 'string' && this._byKey.has(topic);
+    }
+
+    canonical(topic) {
+        if (typeof topic !== 'string') return topic;
+        return this._canonicalByAlias.get(topic) || topic;
+    }
+
+    list() {
+        // Strip handler so callers can safely log / serialise the result
+        // (handler functions are noisy and not contract-relevant).
+        return this._descriptors.map((d) => ({
+            topic: d.topic,
+            aliases: d.aliases.slice(),
+            payloadSchema: d.payloadSchema,
+            description: d.description,
+            units: d.units ? { measure: d.units.measure, default: d.units.default } : null,
+        }));
+    }
+
+    deprecationStats() {
+        const out = {};
+        for (const [alias, count] of this._deprecationCounts) out[alias] = count;
+        return out;
+    }
+
+    async dispatch(msg, source, ctx) {
+        const log = this._loggerFor(ctx);
+        const topic = msg && typeof msg.topic === 'string' ? msg.topic : null;
+        if (!topic) {
+            log.warn?.('commandRegistry: msg has no topic; ignoring');
+            return;
+        }
+        const descriptor = this._byKey.get(topic);
+        if (!descriptor) {
+            log.warn?.(`commandRegistry: unknown topic '${topic}'`);
+            return;
+        }
+        if (topic !== descriptor.topic) this._noteAlias(topic, descriptor.topic, log);
+        if (descriptor.units) this._normaliseUnits(descriptor, msg, log);
+        if (!this._validatePayload(descriptor, msg, log)) return;
+        return descriptor.handler(source, msg, ctx);
+    }
+
+    _noteAlias(alias, canonical, log) {
+        const prev = this._deprecationCounts.get(alias) || 0;
+        this._deprecationCounts.set(alias, prev + 1);
+        if (this._deprecationLogged.has(alias)) return;
+        this._deprecationLogged.add(alias);
+        log.warn?.(`topic '${alias}' is deprecated; use '${canonical}'`);
+    }
+
+    _normaliseUnits(descriptor, msg, log) {
+        const { measure, default: defaultUnit } = descriptor.units;
+        const extracted = _extractValueAndUnit(msg);
+        if (!extracted) return;                       // unknown shape — let payload validator handle it
+        let { value, unit } = extracted;
+        if (unit === undefined || unit === null || unit === '') {
+            // No unit supplied — assume default, silent.
+            msg.payload = value;
+            msg.unit = defaultUnit;
+            return;
+        }
+        const desc = _describeUnit(unit);
+        if (!desc) {
+            log.warn?.(`${descriptor.topic}: unknown unit '${unit}'. Accepted: ${_acceptedList(measure)}. Treating ${value} as ${defaultUnit}.`);
+            msg.payload = value;
+            msg.unit = defaultUnit;
+            return;
+        }
+        if (desc.measure !== measure) {
+            log.warn?.(`${descriptor.topic}: unit '${unit}' is ${desc.measure}, expected ${measure}. Accepted: ${_acceptedList(measure)}. Treating ${value} as ${defaultUnit}.`);
+            msg.payload = value;
+            msg.unit = defaultUnit;
+            return;
+        }
+        try {
+            msg.payload = convert(value).from(unit).to(defaultUnit);
+            msg.unit = defaultUnit;
+        } catch (err) {
+            log.warn?.(`${descriptor.topic}: failed to convert ${value} ${unit} -> ${defaultUnit} (${err.message}). Treating as ${defaultUnit}.`);
+            msg.payload = value;
+            msg.unit = defaultUnit;
+        }
+    }
+
+    _validatePayload(descriptor, msg, log) {
+        const schema = descriptor.payloadSchema;
+        if (!schema) return true;
+        const payload = msg.payload;
+        const type = schema.type || 'any';
+        if (!SCALAR_TYPES.has(type)) {
+            log.warn?.(`commandRegistry: command '${descriptor.topic}' has unknown schema type '${type}'`);
+            return true;
+        }
+        if (type === 'any') return true;
+        if (type === 'none') {
+            if (payload !== undefined && payload !== null) {
+                log.warn?.(`${descriptor.topic}: payload ignored — this is a trigger-only topic`);
+            }
+            return true;
+        }
+        // typeof null === 'object' — explicit null fails an object schema.
+        if (type === 'object') {
+            if (payload === null || typeof payload !== 'object') {
+                log.warn?.(`commandRegistry: '${descriptor.topic}' expected object payload, got ${payload === null ? 'null' : typeof payload}`);
+                return false;
+            }
+        } else if (typeof payload !== type) {
+            log.warn?.(`commandRegistry: '${descriptor.topic}' expected ${type} payload, got ${typeof payload}`);
+            return false;
+        }
+        if (type === 'object' && schema.properties && typeof schema.properties === 'object') {
+            for (const [key, expected] of Object.entries(schema.properties)) {
+                if (!(key in payload)) continue;        // missing keys allowed
+                if (typeof payload[key] !== expected) {
+                    log.warn?.(`commandRegistry: '${descriptor.topic}' payload.${key} expected ${expected}, got ${typeof payload[key]}`);
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+
+    _loggerFor(ctx) {
+        const candidate = (ctx && ctx.logger) || this._logger;
+        return candidate || NOOP_LOGGER;
+    }
+}
+
+const NOOP_LOGGER = { warn() {}, error() {}, info() {}, debug() {} };
+
+function createRegistry(commands, options) {
+    return new CommandRegistry(commands, options);
+}
+
+module.exports = { createRegistry, CommandRegistry };

src/nodered/statusBadge.js

@@ -0,0 +1,96 @@
+/**
+ * statusBadge — small helpers that build Node-RED status objects
+ * ({ fill, shape, text }) consistently across every node.
+ *
+ * See CONTRACTS.md §7. Domains compose badges via these helpers so the
+ * editor look-and-feel converges instead of every node rolling its own
+ * emoji + colour rules.
+ */
+
+'use strict';
+
+const MAX_TEXT = 60;
+const SEPARATOR = ' | ';
+
+const DEFAULT_BADGE = { fill: 'green', shape: 'dot' };
+const ERROR_BADGE   = { fill: 'red',   shape: 'ring' };
+const IDLE_BADGE    = { fill: 'blue',  shape: 'dot' };
+const UNKNOWN_BADGE = { fill: 'grey',  shape: 'ring' };
+
+// Truncate to MAX_TEXT keeping room for the ellipsis. Editor clips the
+// rest visually anyway, but we want the cut to be deterministic so
+// snapshot tests don't drift across Node-RED versions.
+function _clip(text) {
+    if (text == null) return '';
+    const s = String(text);
+    if (s.length <= MAX_TEXT) return s;
+    return s.slice(0, MAX_TEXT - 1) + '…';
+}
+
+function _joinParts(parts) {
+    if (!Array.isArray(parts) || parts.length === 0) return '';
+    const kept = parts.filter((p) => p != null && p !== false && p !== '');
+    if (kept.length === 0) return '';
+    return kept.map(String).join(SEPARATOR);
+}
+
+function compose(parts, opts) {
+    const text = _clip(_joinParts(parts));
+    return {
+        fill:  (opts && opts.fill)  || DEFAULT_BADGE.fill,
+        shape: (opts && opts.shape) || DEFAULT_BADGE.shape,
+        text,
+    };
+}
+
+function error(message) {
+    return {
+        fill:  ERROR_BADGE.fill,
+        shape: ERROR_BADGE.shape,
+        text:  _clip(`⚠ ${message == null ? '' : message}`),
+    };
+}
+
+function idle(label) {
+    return {
+        fill:  IDLE_BADGE.fill,
+        shape: IDLE_BADGE.shape,
+        text:  _clip(`⏸️ ${label == null ? '' : label}`),
+    };
+}
+
+// Look up a state-template badge and optionally compose extra parts
+// into its text. Missing template falls back to a grey "unknown state"
+// badge — silent so caller can still surface the bad state through logs.
+function byState(stateMap, currentState, opts) {
+    const template = stateMap && stateMap[currentState];
+    if (!template) {
+        return {
+            fill:  UNKNOWN_BADGE.fill,
+            shape: UNKNOWN_BADGE.shape,
+            text:  _clip(`unknown state: ${currentState == null ? '' : currentState}`),
+        };
+    }
+    const baseText = template.text == null ? '' : String(template.text);
+    const extras   = opts && Array.isArray(opts.compose) ? opts.compose : [];
+    const merged   = extras.length > 0
+        ? _joinParts([baseText, ...extras])
+        : baseText;
+    return {
+        fill:  template.fill  || DEFAULT_BADGE.fill,
+        shape: template.shape || DEFAULT_BADGE.shape,
+        text:  _clip(merged),
+    };
+}
+
+function text(string, opts) {
+    return {
+        fill:  (opts && opts.fill)  || DEFAULT_BADGE.fill,
+        shape: (opts && opts.shape) || DEFAULT_BADGE.shape,
+        text:  _clip(string == null ? '' : string),
+    };
+}
+
+const statusBadge = { compose, error, idle, byState, text };
+
+module.exports = { statusBadge, MAX_TEXT };

src/nodered/statusUpdater.js

@@ -0,0 +1,90 @@
+/**
+ * StatusUpdater — periodic Node-RED status badge poller.
+ *
+ * Replaces the per-node `_statusInterval` boilerplate (e.g. pumpingStation
+ * nodeClass lines 160-171) with one class. The adapter constructs it once
+ * with a `node` (Node-RED handle) and a `source` (the domain), and the
+ * loop drives `node.status(source.getStatusBadge())` at a fixed cadence.
+ *
+ * Errors thrown from the domain become a red error badge instead of
+ * crashing the interval — operators see the failure in the editor.
+ *
+ * See CONTRACTS.md §7 for the badge shape; statusBadge.js for the helpers.
+ */
+
+'use strict';
+
+const { statusBadge } = require('./statusBadge');
+
+const CLEAR_BADGE = {};
+
+class StatusUpdater {
+    constructor({ node, source, intervalMs, logger } = {}) {
+        if (!node || typeof node.status !== 'function') {
+            throw new Error('StatusUpdater: node must expose a .status(badge) method');
+        }
+        if (!source || typeof source.getStatusBadge !== 'function') {
+            throw new Error('StatusUpdater: source must expose a .getStatusBadge() method');
+        }
+        this._node = node;
+        this._source = source;
+        this._intervalMs = Number.isFinite(intervalMs) ? intervalMs : 0;
+        this._logger = logger || null;
+        this._timer = null;
+    }
+
+    get isRunning() {
+        return this._timer !== null;
+    }
+
+    start() {
+        // intervalMs=0 keeps unit tests / headless harnesses silent.
+        if (this._intervalMs <= 0) return;
+        if (this._timer !== null) return;
+        this._timer = setInterval(() => this._tick(), this._intervalMs);
+    }
+
+    stop() {
+        if (this._timer !== null) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+        // Wipe the badge so a stale label doesn't linger in the editor
+        // after the node is closed/redeployed.
+        try { this._node.status(CLEAR_BADGE); } catch (_) { /* best effort */ }
+    }
+
+    _tick() {
+        let badge;
+        try {
+            badge = this._source.getStatusBadge();
+        } catch (err) {
+            const msg = err && err.message ? err.message : String(err);
+            if (this._logger && typeof this._logger.error === 'function') {
+                this._logger.error(`StatusUpdater: getStatusBadge threw: ${msg}`);
+            }
+            this._safeApply(statusBadge.error(msg));
+            return;
+        }
+        if (badge == null) {
+            this._safeApply(CLEAR_BADGE);
+            return;
+        }
+        this._safeApply(badge);
+    }
+
+    _safeApply(badge) {
+        try {
+            this._node.status(badge);
+        } catch (err) {
+            // node.status itself failing is exotic (e.g. node already
+            // closed). Log once per tick; the next tick will retry.
+            if (this._logger && typeof this._logger.error === 'function') {
+                const msg = err && err.message ? err.message : String(err);
+                this._logger.error(`StatusUpdater: node.status threw: ${msg}`);
+            }
+        }
+    }
+}
+
+module.exports = { StatusUpdater };

src/nrmse/errorMetrics.js

@@ -1,125 +1,126 @@
-//load local dependencies
 const EventEmitter = require('events');
-
-//load all config modules
 const defaultConfig = require('./nrmseConfig.json');
 const ConfigUtils = require('../helper/configUtils');
 
 class ErrorMetrics {
   constructor(config = {}, logger) {
-
-    this.emitter = new EventEmitter();  // Own EventEmitter
+    this.emitter = new EventEmitter();
     this.configUtils = new ConfigUtils(defaultConfig);
     this.config = this.configUtils.initConfig(config);
-  
-    // Init after config is set
     this.logger = logger;
 
-    // For long-term NRMSD accumulation
+    this.metricState = new Map();
+    this.legacyMetricId = 'default';
+
+    // Backward-compatible fields retained for existing callers/tests.
     this.cumNRMSD = 0;
     this.cumCount = 0;
   }
 
-  //INCLUDE timestamps in the next update OLIFANT
-  meanSquaredError(predicted, measured) {
-    if (predicted.length !== measured.length) {
-      this.logger.error("Comparing MSE Arrays must have the same length.");
+  registerMetric(metricId, profile = {}) {
+    const key = String(metricId || this.legacyMetricId);
+    const state = this._ensureMetricState(key);
+    state.profile = { ...state.profile, ...profile };
+    return state.profile;
+  }
+
+  resetMetric(metricId = this.legacyMetricId) {
+    this.metricState.delete(String(metricId));
+    if (metricId === this.legacyMetricId) {
+      this.cumNRMSD = 0;
+      this.cumCount = 0;
+    }
+  }
+
+  getMetricState(metricId = this.legacyMetricId) {
+    return this.metricState.get(String(metricId)) || null;
+  }
+
+  meanSquaredError(predicted, measured, options = {}) {
+    const { p, m } = this._validateSeries(predicted, measured, options);
+    let sumSqError = 0;
+    for (let i = 0; i < p.length; i += 1) {
+      const err = p[i] - m[i];
+      sumSqError += err * err;
+    }
+    return sumSqError / p.length;
+  }
+
+  rootMeanSquaredError(predicted, measured, options = {}) {
+    return Math.sqrt(this.meanSquaredError(predicted, measured, options));
+  }
+
+  normalizedRootMeanSquaredError(predicted, measured, processMin, processMax, options = {}) {
+    const range = Number(processMax) - Number(processMin);
+    if (!Number.isFinite(range) || range <= 0) {
+      this._failOrLog(
+        `Invalid process range: processMax (${processMax}) must be greater than processMin (${processMin}).`,
+        options
+      );
+      return NaN;
+    }
+    const rmse = this.rootMeanSquaredError(predicted, measured, options);
+    return rmse / range;
+  }
+
+  normalizeUsingRealtime(predicted, measured, options = {}) {
+    const { p, m } = this._validateSeries(predicted, measured, options);
+    const realtimeMin = Math.min(Math.min(...p), Math.min(...m));
+    const realtimeMax = Math.max(Math.max(...p), Math.max(...m));
+    const range = realtimeMax - realtimeMin;
+    if (!Number.isFinite(range) || range <= 0) {
+      throw new Error('Invalid process range: processMax must be greater than processMin.');
+    }
+    const rmse = this.rootMeanSquaredError(p, m, options);
+    return rmse / range;
+  }
+
+  longTermNRMSD(input, metricId = this.legacyMetricId, options = {}) {
+    const metricKey = String(metricId || this.legacyMetricId);
+    const state = this._ensureMetricState(metricKey);
+    const profile = this._resolveProfile(metricKey, options);
+    const value = Number(input);
+    if (!Number.isFinite(value)) {
+      this._failOrLog(`longTermNRMSD input must be finite. Received: ${input}`, options);
       return 0;
     }
 
-
-    let sumSqError = 0;
-    for (let i = 0; i < predicted.length; i++) {
-      const err = predicted[i] - measured[i];
-      sumSqError += err * err;
-    }
-    return sumSqError / predicted.length;
-  }
-
-  rootMeanSquaredError(predicted, measured) {
-    return Math.sqrt(this.meanSquaredError(predicted, measured));
-  }
-
-  normalizedRootMeanSquaredError(predicted, measured, processMin, processMax) {
-    const range = processMax - processMin;
-    if (range <= 0) {
-      this.logger.error("Invalid process range: processMax must be greater than processMin.");
-    }
-    const rmse = this.rootMeanSquaredError(predicted, measured);
-    return rmse / range;
-  }
-
-  longTermNRMSD(input) {
-
-    const storedNRMSD = this.cumNRMSD;
-    const storedCount = this.cumCount;
-    const newCount = storedCount + 1;
-    
-    // Update cumulative values
-    this.cumCount = newCount;
-    
-    // Calculate new running average
-    if (storedCount === 0) {
-      this.cumNRMSD = input; // First value
-    } else {
-      // Running average formula: newAvg = oldAvg + (newValue - oldAvg) / newCount
-      this.cumNRMSD = storedNRMSD + (input - storedNRMSD) / newCount;
+    // Keep backward compatibility if callers manipulate cumCount/cumNRMSD directly.
+    if (metricKey === this.legacyMetricId && (state.sampleCount !== this.cumCount || state.longTermEwma !== this.cumNRMSD)) {
+      state.sampleCount = Number(this.cumCount) || 0;
+      state.longTermEwma = Number(this.cumNRMSD) || 0;
     }
 
-    if(newCount >= 100) {
-      // Return the current NRMSD value, not just the contribution from this sample
-      return this.cumNRMSD;
-    }
-    return 0;
-  }
+    state.sampleCount += 1;
+    const alpha = profile.ewmaAlpha;
+    state.longTermEwma = state.sampleCount === 1 ? value : (alpha * value) + ((1 - alpha) * state.longTermEwma);
 
-  normalizeUsingRealtime(predicted, measured) {
-    const realtimeMin = Math.min(Math.min(...predicted), Math.min(...measured));
-    const realtimeMax = Math.max(Math.max(...predicted), Math.max(...measured));
-    const range = realtimeMax - realtimeMin;
-    if (range <= 0) {
-      throw new Error("Invalid process range: processMax must be greater than processMin.");
+    if (metricKey === this.legacyMetricId) {
+      this.cumCount = state.sampleCount;
+      this.cumNRMSD = state.longTermEwma;
     }
-    const rmse = this.rootMeanSquaredError(predicted, measured);
-    return rmse / range;
+
+    if (state.sampleCount < profile.minSamplesForLongTerm) {
+      return 0;
+    }
+    return state.longTermEwma;
   }
 
   detectImmediateDrift(nrmse) {
-    let ImmDrift = {};
-    this.logger.debug(`checking immediate drift with thresholds : ${this.config.thresholds.NRMSE_HIGH} ${this.config.thresholds.NRMSE_MEDIUM} ${this.config.thresholds.NRMSE_LOW}`);
-    switch (true) {
-      case( nrmse > this.config.thresholds.NRMSE_HIGH ) :
-        ImmDrift = {level : 3 , feedback : "High immediate drift detected"};
-        break;
-      case( nrmse > this.config.thresholds.NRMSE_MEDIUM ) :
-        ImmDrift = {level : 2 , feedback : "Medium immediate drift detected"};
-        break;
-      case(nrmse > this.config.thresholds.NRMSE_LOW ):
-        ImmDrift = {level : 1 , feedback : "Low immediate drift detected"};
-        break;
-      default:
-        ImmDrift = {level : 0 , feedback : "No drift detected"};
-    }
-    return ImmDrift;
+    const thresholds = this.config.thresholds;
+    if (nrmse > thresholds.NRMSE_HIGH) return { level: 3, feedback: 'High immediate drift detected' };
+    if (nrmse > thresholds.NRMSE_MEDIUM) return { level: 2, feedback: 'Medium immediate drift detected' };
+    if (nrmse > thresholds.NRMSE_LOW) return { level: 1, feedback: 'Low immediate drift detected' };
+    return { level: 0, feedback: 'No drift detected' };
   }
 
   detectLongTermDrift(longTermNRMSD) {
-    let LongTermDrift = {};
-    this.logger.debug(`checking longterm drift with thresholds : ${this.config.thresholds.LONG_TERM_HIGH} ${this.config.thresholds.LONG_TERM_MEDIUM} ${this.config.thresholds.LONG_TERM_LOW}`);
-    switch (true) {
-      case(Math.abs(longTermNRMSD) > this.config.thresholds.LONG_TERM_HIGH) :
-        LongTermDrift = {level : 3 , feedback : "High long-term drift detected"};
-        break;
-      case (Math.abs(longTermNRMSD) > this.config.thresholds.LONG_TERM_MEDIUM) :
-        LongTermDrift = {level : 2 , feedback : "Medium long-term drift detected"};
-        break;
-      case ( Math.abs(longTermNRMSD) > this.config.thresholds.LONG_TERM_LOW ) :
-        LongTermDrift = {level : 1 , feedback : "Low long-term drift detected"};
-        break;
-      default:
-        LongTermDrift = {level : 0 , feedback : "No drift detected"}; 
-    }
-    return LongTermDrift;
+    const thresholds = this.config.thresholds;
+    const absValue = Math.abs(longTermNRMSD);
+    if (absValue > thresholds.LONG_TERM_HIGH) return { level: 3, feedback: 'High long-term drift detected' };
+    if (absValue > thresholds.LONG_TERM_MEDIUM) return { level: 2, feedback: 'Medium long-term drift detected' };
+    if (absValue > thresholds.LONG_TERM_LOW) return { level: 1, feedback: 'Low long-term drift detected' };
+    return { level: 0, feedback: 'No drift detected' };
   }
 
   detectDrift(nrmse, longTermNRMSD) {
@@ -128,27 +129,272 @@ class ErrorMetrics {
     return { ImmDrift, LongTermDrift };
   }
 
-  // asses the drift
-  assessDrift(predicted, measured, processMin, processMax) {
-    // Compute NRMSE and check for immediate drift
-    const nrmse = this.normalizedRootMeanSquaredError(predicted, measured, processMin, processMax);
-    this.logger.debug(`NRMSE: ${nrmse}`);
-    // cmopute long-term NRMSD and add result to cumalitve NRMSD
-    const longTermNRMSD = this.longTermNRMSD(nrmse);
-    // return the drift
-    // Return the drift assessment object
+  assessDrift(predicted, measured, processMin, processMax, options = {}) {
+    const metricKey = String(options.metricId || this.legacyMetricId);
+    const profile = this._resolveProfile(metricKey, options);
+    const strict = this._resolveStrict(options, profile);
+
+    const aligned = this._alignSeriesByTimestamp(predicted, measured, options, profile);
+    if (!aligned.valid) {
+      if (strict) {
+        throw new Error(aligned.reason);
+      }
+      return this._invalidAssessment(metricKey, aligned.reason);
+    }
+
+    const nrmse = this.normalizedRootMeanSquaredError(
+      aligned.predicted,
+      aligned.measured,
+      processMin,
+      processMax,
+      { ...options, strictValidation: strict }
+    );
+    if (!Number.isFinite(nrmse)) {
+      if (strict) {
+        throw new Error('NRMSE calculation returned a non-finite value.');
+      }
+      return this._invalidAssessment(metricKey, 'non_finite_nrmse');
+    }
+
+    const longTermNRMSD = this.longTermNRMSD(nrmse, metricKey, { ...options, strictValidation: strict });
     const driftAssessment = this.detectDrift(nrmse, longTermNRMSD);
-    return {
+    const state = this._ensureMetricState(metricKey);
+    state.lastResult = {
       nrmse,
       longTermNRMSD,
       immediateLevel: driftAssessment.ImmDrift.level,
       immediateFeedback: driftAssessment.ImmDrift.feedback,
       longTermLevel: driftAssessment.LongTermDrift.level,
-      longTermFeedback: driftAssessment.LongTermDrift.feedback
+      longTermFeedback: driftAssessment.LongTermDrift.feedback,
+      valid: true,
+      metricId: metricKey,
+      sampleCount: state.sampleCount,
+      longTermReady: state.sampleCount >= profile.minSamplesForLongTerm,
+      flags: [],
+    };
+    return state.lastResult;
+  }
+
+  assessPoint(metricId, predictedValue, measuredValue, options = {}) {
+    const metricKey = String(metricId || this.legacyMetricId);
+    const profile = this._resolveProfile(metricKey, options);
+    const state = this._ensureMetricState(metricKey);
+    const strict = this._resolveStrict(options, profile);
+
+    const p = Number(predictedValue);
+    const m = Number(measuredValue);
+    if (!Number.isFinite(p) || !Number.isFinite(m)) {
+      const reason = `assessPoint requires finite numbers. predicted=${predictedValue}, measured=${measuredValue}`;
+      if (strict) {
+        throw new Error(reason);
+      }
+      return this._invalidAssessment(metricKey, reason);
+    }
+
+    const predictedTimestamp = Number(options.predictedTimestamp ?? options.timestamp ?? Date.now());
+    const measuredTimestamp = Number(options.measuredTimestamp ?? options.timestamp ?? Date.now());
+    const delta = Math.abs(predictedTimestamp - measuredTimestamp);
+    if (delta > profile.alignmentToleranceMs) {
+      const reason = `Sample timestamp delta (${delta} ms) exceeds tolerance (${profile.alignmentToleranceMs} ms)`;
+      if (strict) {
+        throw new Error(reason);
+      }
+      return this._invalidAssessment(metricKey, reason);
+    }
+
+    state.predicted.push(p);
+    state.measured.push(m);
+    state.predictedTimestamps.push(predictedTimestamp);
+    state.measuredTimestamps.push(measuredTimestamp);
+
+    while (state.predicted.length > profile.windowSize) state.predicted.shift();
+    while (state.measured.length > profile.windowSize) state.measured.shift();
+    while (state.predictedTimestamps.length > profile.windowSize) state.predictedTimestamps.shift();
+    while (state.measuredTimestamps.length > profile.windowSize) state.measuredTimestamps.shift();
+
+    if (state.predicted.length < 2 || state.measured.length < 2) {
+      return this._invalidAssessment(metricKey, 'insufficient_samples');
+    }
+
+    let processMin = Number(options.processMin);
+    let processMax = Number(options.processMax);
+    if (!Number.isFinite(processMin) || !Number.isFinite(processMax) || processMax <= processMin) {
+      processMin = Math.min(...state.predicted, ...state.measured);
+      processMax = Math.max(...state.predicted, ...state.measured);
+      if (!Number.isFinite(processMin) || !Number.isFinite(processMax) || processMax <= processMin) {
+        processMin = 0;
+        processMax = 1;
+      }
+    }
+
+    return this.assessDrift(state.predicted, state.measured, processMin, processMax, {
+      ...options,
+      metricId: metricKey,
+      strictValidation: strict,
+      predictedTimestamps: state.predictedTimestamps,
+      measuredTimestamps: state.measuredTimestamps,
+    });
+  }
+
+  _ensureMetricState(metricId) {
+    const key = String(metricId || this.legacyMetricId);
+    if (!this.metricState.has(key)) {
+      this.metricState.set(key, {
+        predicted: [],
+        measured: [],
+        predictedTimestamps: [],
+        measuredTimestamps: [],
+        sampleCount: 0,
+        longTermEwma: 0,
+        profile: {},
+        lastResult: null,
+      });
+    }
+    return this.metricState.get(key);
+  }
+
+  _resolveProfile(metricId, options = {}) {
+    const state = this._ensureMetricState(metricId);
+    const base = this.config.processing || {};
+    return {
+      windowSize: Number(options.windowSize ?? state.profile.windowSize ?? base.windowSize ?? 50),
+      minSamplesForLongTerm: Number(options.minSamplesForLongTerm ?? state.profile.minSamplesForLongTerm ?? base.minSamplesForLongTerm ?? 100),
+      ewmaAlpha: Number(options.ewmaAlpha ?? state.profile.ewmaAlpha ?? base.ewmaAlpha ?? 0.1),
+      alignmentToleranceMs: Number(options.alignmentToleranceMs ?? state.profile.alignmentToleranceMs ?? base.alignmentToleranceMs ?? 2000),
+      strictValidation: Boolean(options.strictValidation ?? state.profile.strictValidation ?? base.strictValidation ?? true),
     };
   }
 
+  _resolveStrict(options = {}, profile = null) {
+    if (Object.prototype.hasOwnProperty.call(options, 'strictValidation')) {
+      return Boolean(options.strictValidation);
+    }
+    if (profile && Object.prototype.hasOwnProperty.call(profile, 'strictValidation')) {
+      return Boolean(profile.strictValidation);
+    }
+    return Boolean(this.config.processing?.strictValidation ?? true);
+  }
 
+  _validateSeries(predicted, measured, options = {}) {
+    if (!Array.isArray(predicted) || !Array.isArray(measured)) {
+      this._failOrLog('predicted and measured must be arrays.', options);
+      return { p: [], m: [] };
+    }
+    if (!predicted.length || !measured.length) {
+      this._failOrLog('predicted and measured arrays must not be empty.', options);
+      return { p: [], m: [] };
+    }
+    if (predicted.length !== measured.length) {
+      this._failOrLog('predicted and measured arrays must have the same length.', options);
+      return { p: [], m: [] };
+    }
+
+    const p = predicted.map(Number);
+    const m = measured.map(Number);
+    const hasBad = p.some((v) => !Number.isFinite(v)) || m.some((v) => !Number.isFinite(v));
+    if (hasBad) {
+      this._failOrLog('predicted and measured arrays must contain finite numeric values.', options);
+      return { p: [], m: [] };
+    }
+    return { p, m };
+  }
+
+  _alignSeriesByTimestamp(predicted, measured, options = {}, profile = null) {
+    const strict = this._resolveStrict(options, profile);
+    const tolerance = Number(options.alignmentToleranceMs ?? profile?.alignmentToleranceMs ?? 2000);
+    const predictedTimestamps = Array.isArray(options.predictedTimestamps) ? options.predictedTimestamps.map(Number) : null;
+    const measuredTimestamps = Array.isArray(options.measuredTimestamps) ? options.measuredTimestamps.map(Number) : null;
+
+    if (!predictedTimestamps || !measuredTimestamps) {
+      if (!Array.isArray(predicted) || !Array.isArray(measured)) {
+        return { valid: false, reason: 'predicted and measured must be arrays.' };
+      }
+      if (predicted.length !== measured.length) {
+        const reason = `Series length mismatch without timestamps: predicted=${predicted.length}, measured=${measured.length}`;
+        if (strict) return { valid: false, reason };
+        const n = Math.min(predicted.length, measured.length);
+        if (n < 2) return { valid: false, reason };
+        return {
+          valid: true,
+          predicted: predicted.slice(-n).map(Number),
+          measured: measured.slice(-n).map(Number),
+          flags: ['length_mismatch_realigned'],
+        };
+      }
+      try {
+        const { p, m } = this._validateSeries(predicted, measured, { ...options, strictValidation: true });
+        return { valid: true, predicted: p, measured: m, flags: [] };
+      } catch (error) {
+        return { valid: false, reason: error.message };
+      }
+    }
+
+    if (!Array.isArray(predicted) || !Array.isArray(measured)) {
+      return { valid: false, reason: 'predicted and measured must be arrays.' };
+    }
+    if (predicted.length !== predictedTimestamps.length || measured.length !== measuredTimestamps.length) {
+      return { valid: false, reason: 'timestamp arrays must match value-array lengths.' };
+    }
+
+    const predictedSamples = predicted
+      .map((v, i) => ({ value: Number(v), ts: predictedTimestamps[i] }))
+      .filter((s) => Number.isFinite(s.value) && Number.isFinite(s.ts))
+      .sort((a, b) => a.ts - b.ts);
+    const measuredSamples = measured
+      .map((v, i) => ({ value: Number(v), ts: measuredTimestamps[i] }))
+      .filter((s) => Number.isFinite(s.value) && Number.isFinite(s.ts))
+      .sort((a, b) => a.ts - b.ts);
+
+    const alignedPredicted = [];
+    const alignedMeasured = [];
+    let i = 0;
+    let j = 0;
+    while (i < predictedSamples.length && j < measuredSamples.length) {
+      const p = predictedSamples[i];
+      const m = measuredSamples[j];
+      const delta = p.ts - m.ts;
+      if (Math.abs(delta) <= tolerance) {
+        alignedPredicted.push(p.value);
+        alignedMeasured.push(m.value);
+        i += 1;
+        j += 1;
+      } else if (delta < 0) {
+        i += 1;
+      } else {
+        j += 1;
+      }
+    }
+
+    if (alignedPredicted.length < 2 || alignedMeasured.length < 2) {
+      return { valid: false, reason: 'insufficient aligned samples after timestamp matching.' };
+    }
+
+    return { valid: true, predicted: alignedPredicted, measured: alignedMeasured, flags: [] };
+  }
+
+  _invalidAssessment(metricId, reason) {
+    return {
+      nrmse: NaN,
+      longTermNRMSD: 0,
+      immediateLevel: 0,
+      immediateFeedback: 'Drift assessment unavailable',
+      longTermLevel: 0,
+      longTermFeedback: 'Drift assessment unavailable',
+      valid: false,
+      metricId: String(metricId || this.legacyMetricId),
+      sampleCount: this._ensureMetricState(metricId).sampleCount,
+      longTermReady: false,
+      flags: [reason],
+    };
+  }
+
+  _failOrLog(message, options = {}) {
+    const strict = this._resolveStrict(options);
+    if (strict) {
+      throw new Error(message);
+    }
+    this.logger?.warn?.(message);
+  }
 }
 
 module.exports = ErrorMetrics;

src/nrmse/index.js

@@ -0,0 +1,7 @@
+const nrmse = require('./errorMetrics.js');
+const nrmseConfig = require('./nrmseConfig.json');
+
+module.exports = {
+  nrmse,
+  nrmseConfig,
+};

src/nrmse/nrmseConfig.json

@@ -1,7 +1,7 @@
 {
   "general": {
     "name": {
-      "default": "ErrorMetrics",
+      "default": "errormetrics",
       "rules": {
         "type": "string",
         "description": "A human-readable name for the configuration."
@@ -58,7 +58,7 @@
   },
   "functionality": {
     "softwareType": {
-      "default": "errorMetrics",
+      "default": "errormetrics",
       "rules": {
         "type": "string",
         "description": "Logical name identifying the software type."
@@ -134,5 +134,47 @@
         "description": "High threshold for long-term normalized root mean squared deviation."
       }
     }
+  },
+  "processing": {
+    "windowSize": {
+      "default": 50,
+      "rules": {
+        "type": "integer",
+        "min": 2,
+        "description": "Rolling sample window size used for drift evaluation."
+      }
+    },
+    "minSamplesForLongTerm": {
+      "default": 100,
+      "rules": {
+        "type": "integer",
+        "min": 1,
+        "description": "Minimum sample count before long-term drift is considered mature."
+      }
+    },
+    "ewmaAlpha": {
+      "default": 0.1,
+      "rules": {
+        "type": "number",
+        "min": 0.001,
+        "max": 1,
+        "description": "EWMA smoothing factor for long-term drift trend."
+      }
+    },
+    "alignmentToleranceMs": {
+      "default": 2000,
+      "rules": {
+        "type": "integer",
+        "min": 0,
+        "description": "Maximum timestamp delta allowed between predicted and measured sample pairs."
+      }
+    },
+    "strictValidation": {
+      "default": true,
+      "rules": {
+        "type": "boolean",
+        "description": "When true, invalid inputs raise errors instead of producing silent outputs."
+      }
+    }
   }
 }

src/outliers/index.js

@@ -0,0 +1,5 @@
+const outlierDetection = require('./outlierDetection.js');
+
+module.exports = {
+  outlierDetection,
+};

src/outliers/outlierDetection.js

@@ -61,6 +61,8 @@ class DynamicClusterDeviation {
     }
 }
 
+module.exports = DynamicClusterDeviation;
+
 // Rolling window simulation with outlier detection
 /*
 const detector = new DynamicClusterDeviation();
@@ -87,5 +89,3 @@ dataStream.forEach((value, index) => {
 
 console.log("\nFinal detector cluster states:", JSON.stringify(detector.clusters, null, 2));
 */
-
-module.exports = DynamicClusterDeviation;

src/pid/PIDController.js

@@ -0,0 +1,663 @@
+'use strict';
+
+/**
+ * Production-focused discrete PID controller with modern control features:
+ * - auto/manual and bumpless transfer
+ * - freeze/unfreeze (hold output while optionally tracking process)
+ * - derivative filtering and derivative-on-measurement/error
+ * - anti-windup (clamp or back-calculation)
+ * - output and integral limits
+ * - output rate limiting
+ * - deadband
+ * - gain scheduling (array/function)
+ * - feedforward and dynamic tunings at runtime
+ */
+class PIDController {
+  constructor(options = {}) {
+    const {
+      kp = 1,
+      ki = 0,
+      kd = 0,
+      sampleTime = 1000,
+      derivativeFilter = 0.15,
+      outputMin = Number.NEGATIVE_INFINITY,
+      outputMax = Number.POSITIVE_INFINITY,
+      integralMin = null,
+      integralMax = null,
+      derivativeOnMeasurement = true,
+      setpointWeight = 1,
+      derivativeWeight = 0,
+      deadband = 0,
+      outputRateLimitUp = Number.POSITIVE_INFINITY,
+      outputRateLimitDown = Number.POSITIVE_INFINITY,
+      antiWindupMode = 'clamp',
+      backCalculationGain = 0,
+      gainSchedule = null,
+      autoMode = true,
+      trackOnManual = true,
+      frozen = false,
+      freezeTrackMeasurement = true,
+      freezeTrackError = false,
+    } = options;
+
+    this.kp = 0;
+    this.ki = 0;
+    this.kd = 0;
+
+    this.setTunings({ kp, ki, kd });
+    this.setSampleTime(sampleTime);
+    this.setOutputLimits(outputMin, outputMax);
+    this.setIntegralLimits(integralMin, integralMax);
+    this.setDerivativeFilter(derivativeFilter);
+    this.setSetpointWeights({ beta: setpointWeight, gamma: derivativeWeight });
+    this.setDeadband(deadband);
+    this.setOutputRateLimits(outputRateLimitUp, outputRateLimitDown);
+    this.setAntiWindup({ mode: antiWindupMode, backCalculationGain });
+    this.setGainSchedule(gainSchedule);
+
+    this.derivativeOnMeasurement = Boolean(derivativeOnMeasurement);
+    this.autoMode = Boolean(autoMode);
+    this.trackOnManual = Boolean(trackOnManual);
+
+    this.frozen = Boolean(frozen);
+    this.freezeTrackMeasurement = Boolean(freezeTrackMeasurement);
+    this.freezeTrackError = Boolean(freezeTrackError);
+
+    this.reset();
+  }
+
+  setTunings({ kp = this.kp, ki = this.ki, kd = this.kd } = {}) {
+    [kp, ki, kd].forEach((gain, index) => {
+      if (!Number.isFinite(gain)) {
+        const label = ['kp', 'ki', 'kd'][index];
+        throw new TypeError(`${label} must be a finite number`);
+      }
+    });
+
+    this.kp = kp;
+    this.ki = ki;
+    this.kd = kd;
+    return this;
+  }
+
+  setSampleTime(sampleTimeMs = this.sampleTime) {
+    if (!Number.isFinite(sampleTimeMs) || sampleTimeMs <= 0) {
+      throw new RangeError('sampleTime must be a positive number of milliseconds');
+    }
+
+    this.sampleTime = sampleTimeMs;
+    return this;
+  }
+
+  setOutputLimits(min = this.outputMin, max = this.outputMax) {
+    if (!Number.isFinite(min) && min !== Number.NEGATIVE_INFINITY) {
+      throw new TypeError('outputMin must be finite or -Infinity');
+    }
+    if (!Number.isFinite(max) && max !== Number.POSITIVE_INFINITY) {
+      throw new TypeError('outputMax must be finite or Infinity');
+    }
+    if (min >= max) {
+      throw new RangeError('outputMin must be smaller than outputMax');
+    }
+
+    this.outputMin = min;
+    this.outputMax = max;
+    this.lastOutput = this._clamp(this.lastOutput ?? 0, this.outputMin, this.outputMax);
+    return this;
+  }
+
+  setIntegralLimits(min = this.integralMin ?? null, max = this.integralMax ?? null) {
+    if (min !== null && !Number.isFinite(min)) {
+      throw new TypeError('integralMin must be null or a finite number');
+    }
+    if (max !== null && !Number.isFinite(max)) {
+      throw new TypeError('integralMax must be null or a finite number');
+    }
+    if (min !== null && max !== null && min > max) {
+      throw new RangeError('integralMin must be smaller than integralMax');
+    }
+
+    this.integralMin = min;
+    this.integralMax = max;
+    this.integral = this._applyIntegralLimits(this.integral ?? 0);
+    return this;
+  }
+
+  setDerivativeFilter(value = this.derivativeFilter ?? 0) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+      throw new RangeError('derivativeFilter must be between 0 and 1');
+    }
+
+    this.derivativeFilter = value;
+    return this;
+  }
+
+  setSetpointWeights({ beta = this.setpointWeight ?? 1, gamma = this.derivativeWeight ?? 0 } = {}) {
+    if (!Number.isFinite(beta) || !Number.isFinite(gamma)) {
+      throw new TypeError('setpoint and derivative weights must be finite numbers');
+    }
+
+    this.setpointWeight = beta;
+    this.derivativeWeight = gamma;
+    return this;
+  }
+
+  setDeadband(value = this.deadband ?? 0) {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new RangeError('deadband must be a non-negative finite number');
+    }
+
+    this.deadband = value;
+    return this;
+  }
+
+  setOutputRateLimits(up = this.outputRateLimitUp, down = this.outputRateLimitDown) {
+    if (!Number.isFinite(up) && up !== Number.POSITIVE_INFINITY) {
+      throw new TypeError('outputRateLimitUp must be finite or Infinity');
+    }
+    if (!Number.isFinite(down) && down !== Number.POSITIVE_INFINITY) {
+      throw new TypeError('outputRateLimitDown must be finite or Infinity');
+    }
+    if (up <= 0 || down <= 0) {
+      throw new RangeError('output rate limits must be positive values');
+    }
+
+    this.outputRateLimitUp = up;
+    this.outputRateLimitDown = down;
+    return this;
+  }
+
+  setAntiWindup({ mode = this.antiWindupMode ?? 'clamp', backCalculationGain = this.backCalculationGain ?? 0 } = {}) {
+    const normalized = String(mode || 'clamp').trim().toLowerCase();
+    if (normalized !== 'clamp' && normalized !== 'backcalc') {
+      throw new RangeError('anti windup mode must be "clamp" or "backcalc"');
+    }
+    if (!Number.isFinite(backCalculationGain) || backCalculationGain < 0) {
+      throw new RangeError('backCalculationGain must be a non-negative finite number');
+    }
+
+    this.antiWindupMode = normalized;
+    this.backCalculationGain = backCalculationGain;
+    return this;
+  }
+
+  /**
+   * Gain schedule options:
+   * - null: disabled
+   * - function(input, state) => { kp, ki, kd }
+   * - array: [{ min, max, kp, ki, kd }, ...]
+   */
+  setGainSchedule(schedule = null) {
+    if (schedule == null) {
+      this.gainSchedule = null;
+      return this;
+    }
+
+    if (typeof schedule === 'function') {
+      this.gainSchedule = schedule;
+      return this;
+    }
+
+    if (!Array.isArray(schedule)) {
+      throw new TypeError('gainSchedule must be null, a function, or an array');
+    }
+
+    schedule.forEach((entry, index) => {
+      if (!entry || typeof entry !== 'object') {
+        throw new TypeError(`gainSchedule[${index}] must be an object`);
+      }
+      const { min = Number.NEGATIVE_INFINITY, max = Number.POSITIVE_INFINITY, kp, ki, kd } = entry;
+      if (!Number.isFinite(min) && min !== Number.NEGATIVE_INFINITY) {
+        throw new TypeError(`gainSchedule[${index}].min must be finite or -Infinity`);
+      }
+      if (!Number.isFinite(max) && max !== Number.POSITIVE_INFINITY) {
+        throw new TypeError(`gainSchedule[${index}].max must be finite or Infinity`);
+      }
+      if (min >= max) {
+        throw new RangeError(`gainSchedule[${index}] min must be smaller than max`);
+      }
+      [kp, ki, kd].forEach((value, gainIndex) => {
+        const label = ['kp', 'ki', 'kd'][gainIndex];
+        if (!Number.isFinite(value)) {
+          throw new TypeError(`gainSchedule[${index}].${label} must be finite`);
+        }
+      });
+    });
+
+    this.gainSchedule = schedule;
+    return this;
+  }
+
+  setMode(mode, options = {}) {
+    if (mode !== 'automatic' && mode !== 'manual') {
+      throw new Error('mode must be either "automatic" or "manual"');
+    }
+
+    const nextAuto = mode === 'automatic';
+    const previousAuto = this.autoMode;
+    this.autoMode = nextAuto;
+
+    if (options && Number.isFinite(options.manualOutput)) {
+      this.setManualOutput(options.manualOutput);
+    }
+
+    if (!previousAuto && nextAuto) {
+      this._initializeForAuto(options);
+    }
+
+    return this;
+  }
+
+  freeze(options = {}) {
+    this.frozen = true;
+    this.freezeTrackMeasurement = options.trackMeasurement !== false;
+    this.freezeTrackError = Boolean(options.trackError);
+
+    if (Number.isFinite(options.output)) {
+      this.setManualOutput(options.output);
+    }
+
+    return this;
+  }
+
+  unfreeze() {
+    this.frozen = false;
+    return this;
+  }
+
+  isFrozen() {
+    return this.frozen;
+  }
+
+  setManualOutput(value) {
+    this._assertNumeric('manual output', value);
+    this.lastOutput = this._clamp(value, this.outputMin, this.outputMax);
+    return this.lastOutput;
+  }
+
+  reset(state = {}) {
+    const {
+      integral = 0,
+      lastOutput = 0,
+      timestamp = null,
+      prevMeasurement = null,
+      prevError = null,
+      prevDerivativeInput = null,
+      derivativeState = 0,
+    } = state;
+
+    this.integral = this._applyIntegralLimits(Number.isFinite(integral) ? integral : 0);
+    this.prevError = Number.isFinite(prevError) ? prevError : null;
+    this.prevMeasurement = Number.isFinite(prevMeasurement) ? prevMeasurement : null;
+    this.prevDerivativeInput = Number.isFinite(prevDerivativeInput) ? prevDerivativeInput : null;
+    this.lastOutput = this._clamp(
+      Number.isFinite(lastOutput) ? lastOutput : 0,
+      this.outputMin ?? Number.NEGATIVE_INFINITY,
+      this.outputMax ?? Number.POSITIVE_INFINITY
+    );
+    this.lastTimestamp = Number.isFinite(timestamp) ? timestamp : null;
+    this.derivativeState = Number.isFinite(derivativeState) ? derivativeState : 0;
+
+    return this;
+  }
+
+  update(setpoint, measurement, timestamp = Date.now(), options = {}) {
+    if (timestamp && typeof timestamp === 'object' && options && Object.keys(options).length === 0) {
+      options = timestamp;
+      timestamp = Date.now();
+    }
+
+    this._assertNumeric('setpoint', setpoint);
+    this._assertNumeric('measurement', measurement);
+    this._assertNumeric('timestamp', timestamp);
+
+    const opts = options || {};
+
+    if (opts.tunings && typeof opts.tunings === 'object') {
+      this.setTunings(opts.tunings);
+    }
+
+    if (Number.isFinite(opts.gainInput)) {
+      this._applyGainSchedule(opts.gainInput, { setpoint, measurement, timestamp });
+    }
+
+    if (typeof opts.setMode === 'string') {
+      this.setMode(opts.setMode, opts);
+    }
+
+    if (opts.freeze === true) this.freeze(opts);
+    if (opts.unfreeze === true) this.unfreeze();
+
+    if (Number.isFinite(opts.manualOutput)) {
+      this.setManualOutput(opts.manualOutput);
+    }
+
+    const feedForward = Number.isFinite(opts.feedForward) ? opts.feedForward : 0;
+    const force = Boolean(opts.force);
+
+    const error = setpoint - measurement;
+
+    if (!this.autoMode) {
+      if (this.trackOnManual) {
+        this._trackProcessState(setpoint, measurement, error, timestamp);
+      }
+      return this.lastOutput;
+    }
+
+    if (this.frozen) {
+      if (this.freezeTrackMeasurement || this.freezeTrackError) {
+        this._trackProcessState(setpoint, measurement, error, timestamp, {
+          trackMeasurement: this.freezeTrackMeasurement,
+          trackError: this.freezeTrackError,
+        });
+      }
+      return this.lastOutput;
+    }
+
+    if (!force && this.lastTimestamp !== null && (timestamp - this.lastTimestamp) < this.sampleTime) {
+      return this.lastOutput;
+    }
+
+    const elapsedMs = this.lastTimestamp === null ? this.sampleTime : (timestamp - this.lastTimestamp);
+    const dtSeconds = Math.max(elapsedMs / 1000, Number.EPSILON);
+
+    const inDeadband = Math.abs(error) <= this.deadband;
+    if (inDeadband) {
+      this.prevError = error;
+      this.prevMeasurement = measurement;
+      this.prevDerivativeInput = this.derivativeOnMeasurement
+        ? measurement
+        : ((this.derivativeWeight * setpoint) - measurement);
+      this.lastTimestamp = timestamp;
+      return this.lastOutput;
+    }
+
+    const effectiveError = error;
+
+    const pInput = (this.setpointWeight * setpoint) - measurement;
+    const pTerm = this.kp * pInput;
+
+    const derivativeRaw = this._computeDerivative({ setpoint, measurement, error, dtSeconds });
+    this.derivativeState = this.derivativeFilter === 0
+      ? derivativeRaw
+      : this.derivativeState + (derivativeRaw - this.derivativeState) * (1 - this.derivativeFilter);
+
+    const dTerm = this.kd * this.derivativeState;
+
+    const nextIntegral = this._applyIntegralLimits(this.integral + (effectiveError * dtSeconds));
+    let unclampedOutput = pTerm + (this.ki * nextIntegral) + dTerm + feedForward;
+    let clampedOutput = this._clamp(unclampedOutput, this.outputMin, this.outputMax);
+
+    if (this.antiWindupMode === 'backcalc' && this.ki !== 0 && this.backCalculationGain > 0) {
+      const correctedIntegral = nextIntegral + ((clampedOutput - unclampedOutput) * this.backCalculationGain * dtSeconds);
+      this.integral = this._applyIntegralLimits(correctedIntegral);
+    } else {
+      const saturatingHigh = clampedOutput >= this.outputMax && effectiveError > 0;
+      const saturatingLow = clampedOutput <= this.outputMin && effectiveError < 0;
+      this.integral = (saturatingHigh || saturatingLow) ? this.integral : nextIntegral;
+    }
+
+    let output = pTerm + (this.ki * this.integral) + dTerm + feedForward;
+    output = this._clamp(output, this.outputMin, this.outputMax);
+
+    if (this.lastTimestamp !== null) {
+      output = this._applyRateLimit(output, this.lastOutput, dtSeconds);
+    }
+
+    if (Number.isFinite(opts.trackingOutput)) {
+      this._trackIntegralToOutput(opts.trackingOutput, { pTerm, dTerm, feedForward });
+      output = this._clamp(opts.trackingOutput, this.outputMin, this.outputMax);
+    }
+
+    this.lastOutput = output;
+    this.prevError = error;
+    this.prevMeasurement = measurement;
+    this.prevDerivativeInput = this.derivativeOnMeasurement
+      ? measurement
+      : ((this.derivativeWeight * setpoint) - measurement);
+    this.lastTimestamp = timestamp;
+
+    return this.lastOutput;
+  }
+
+  getState() {
+    return {
+      kp: this.kp,
+      ki: this.ki,
+      kd: this.kd,
+      sampleTime: this.sampleTime,
+      outputLimits: { min: this.outputMin, max: this.outputMax },
+      integralLimits: { min: this.integralMin, max: this.integralMax },
+      derivativeFilter: this.derivativeFilter,
+      derivativeOnMeasurement: this.derivativeOnMeasurement,
+      setpointWeight: this.setpointWeight,
+      derivativeWeight: this.derivativeWeight,
+      deadband: this.deadband,
+      outputRateLimits: { up: this.outputRateLimitUp, down: this.outputRateLimitDown },
+      antiWindupMode: this.antiWindupMode,
+      backCalculationGain: this.backCalculationGain,
+      autoMode: this.autoMode,
+      frozen: this.frozen,
+      integral: this.integral,
+      derivativeState: this.derivativeState,
+      lastOutput: this.lastOutput,
+      lastTimestamp: this.lastTimestamp,
+    };
+  }
+
+  getLastOutput() {
+    return this.lastOutput;
+  }
+
+  _initializeForAuto(options = {}) {
+    const setpoint = Number.isFinite(options.setpoint) ? options.setpoint : null;
+    const measurement = Number.isFinite(options.measurement) ? options.measurement : null;
+    const timestamp = Number.isFinite(options.timestamp) ? options.timestamp : Date.now();
+
+    if (measurement !== null) {
+      this.prevMeasurement = measurement;
+    }
+    if (setpoint !== null && measurement !== null) {
+      this.prevError = setpoint - measurement;
+      this.prevDerivativeInput = this.derivativeOnMeasurement
+        ? measurement
+        : ((this.derivativeWeight * setpoint) - measurement);
+    }
+
+    this.lastTimestamp = timestamp;
+
+    if (this.ki !== 0 && setpoint !== null && measurement !== null) {
+      const pTerm = this.kp * ((this.setpointWeight * setpoint) - measurement);
+      const dTerm = this.kd * this.derivativeState;
+      const trackedIntegral = (this.lastOutput - pTerm - dTerm) / this.ki;
+      this.integral = this._applyIntegralLimits(Number.isFinite(trackedIntegral) ? trackedIntegral : this.integral);
+    }
+  }
+
+  _trackProcessState(setpoint, measurement, error, timestamp, tracking = {}) {
+    const trackMeasurement = tracking.trackMeasurement !== false;
+    const trackError = Boolean(tracking.trackError);
+
+    if (trackMeasurement) {
+      this.prevMeasurement = measurement;
+      this.prevDerivativeInput = this.derivativeOnMeasurement
+        ? measurement
+        : ((this.derivativeWeight * setpoint) - measurement);
+    }
+
+    if (trackError) {
+      this.prevError = error;
+    }
+
+    this.lastTimestamp = timestamp;
+  }
+
+  _trackIntegralToOutput(trackingOutput, terms) {
+    if (this.ki === 0) return;
+    const { pTerm, dTerm, feedForward } = terms;
+    const targetIntegral = (trackingOutput - pTerm - dTerm - feedForward) / this.ki;
+    if (Number.isFinite(targetIntegral)) {
+      this.integral = this._applyIntegralLimits(targetIntegral);
+    }
+  }
+
+  _applyGainSchedule(input, state) {
+    if (!this.gainSchedule) return;
+
+    if (typeof this.gainSchedule === 'function') {
+      const tunings = this.gainSchedule(input, this.getState(), state);
+      if (tunings && typeof tunings === 'object') {
+        this.setTunings(tunings);
+      }
+      return;
+    }
+
+    const matched = this.gainSchedule.find((entry) => input >= entry.min && input < entry.max);
+    if (matched) {
+      this.setTunings({ kp: matched.kp, ki: matched.ki, kd: matched.kd });
+    }
+  }
+
+  _computeDerivative({ setpoint, measurement, error, dtSeconds }) {
+    if (!(dtSeconds > 0) || !Number.isFinite(dtSeconds)) {
+      return 0;
+    }
+
+    if (this.derivativeOnMeasurement) {
+      if (this.prevMeasurement === null) return 0;
+      return -(measurement - this.prevMeasurement) / dtSeconds;
+    }
+
+    const derivativeInput = (this.derivativeWeight * setpoint) - measurement;
+    if (this.prevDerivativeInput === null) return 0;
+    const derivativeFromInput = (derivativeInput - this.prevDerivativeInput) / dtSeconds;
+
+    if (Number.isFinite(derivativeFromInput)) {
+      return derivativeFromInput;
+    }
+
+    if (this.prevError === null) return 0;
+    return (error - this.prevError) / dtSeconds;
+  }
+
+  _applyRateLimit(nextOutput, previousOutput, dtSeconds) {
+    const maxRise = Number.isFinite(this.outputRateLimitUp)
+      ? this.outputRateLimitUp * dtSeconds
+      : Number.POSITIVE_INFINITY;
+    const maxFall = Number.isFinite(this.outputRateLimitDown)
+      ? this.outputRateLimitDown * dtSeconds
+      : Number.POSITIVE_INFINITY;
+
+    const lower = previousOutput - maxFall;
+    const upper = previousOutput + maxRise;
+    return this._clamp(nextOutput, lower, upper);
+  }
+
+  _applyIntegralLimits(value) {
+    if (!Number.isFinite(value)) {
+      return 0;
+    }
+
+    let result = value;
+    if (this.integralMin !== null && result < this.integralMin) {
+      result = this.integralMin;
+    }
+    if (this.integralMax !== null && result > this.integralMax) {
+      result = this.integralMax;
+    }
+    return result;
+  }
+
+  _assertNumeric(label, value) {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`${label} must be a finite number`);
+    }
+  }
+
+  _clamp(value, min, max) {
+    if (value < min) return min;
+    if (value > max) return max;
+    return value;
+  }
+}
+
+/**
+ * Cascade PID utility:
+ * - primary PID controls the outer variable
+ * - primary output becomes setpoint for secondary PID
+ */
+class CascadePIDController {
+  constructor(options = {}) {
+    const {
+      primary = {},
+      secondary = {},
+    } = options;
+
+    this.primary = primary instanceof PIDController ? primary : new PIDController(primary);
+    this.secondary = secondary instanceof PIDController ? secondary : new PIDController(secondary);
+  }
+
+  update({
+    setpoint,
+    primaryMeasurement,
+    secondaryMeasurement,
+    timestamp = Date.now(),
+    primaryOptions = {},
+    secondaryOptions = {},
+  } = {}) {
+    if (!Number.isFinite(setpoint)) {
+      throw new TypeError('setpoint must be a finite number');
+    }
+    if (!Number.isFinite(primaryMeasurement)) {
+      throw new TypeError('primaryMeasurement must be a finite number');
+    }
+    if (!Number.isFinite(secondaryMeasurement)) {
+      throw new TypeError('secondaryMeasurement must be a finite number');
+    }
+
+    const secondarySetpoint = this.primary.update(setpoint, primaryMeasurement, timestamp, primaryOptions);
+    const controlOutput = this.secondary.update(secondarySetpoint, secondaryMeasurement, timestamp, secondaryOptions);
+
+    return {
+      primaryOutput: secondarySetpoint,
+      secondaryOutput: controlOutput,
+      state: this.getState(),
+    };
+  }
+
+  setMode(mode, options = {}) {
+    this.primary.setMode(mode, options.primary || options);
+    this.secondary.setMode(mode, options.secondary || options);
+    return this;
+  }
+
+  freeze(options = {}) {
+    this.primary.freeze(options.primary || options);
+    this.secondary.freeze(options.secondary || options);
+    return this;
+  }
+
+  unfreeze() {
+    this.primary.unfreeze();
+    this.secondary.unfreeze();
+    return this;
+  }
+
+  reset(state = {}) {
+    this.primary.reset(state.primary || {});
+    this.secondary.reset(state.secondary || {});
+    return this;
+  }
+
+  getState() {
+    return {
+      primary: this.primary.getState(),
+      secondary: this.secondary.getState(),
+    };
+  }
+}
+
+module.exports = {
+  PIDController,
+  CascadePIDController,
+};

src/pid/examples.js

@@ -0,0 +1,87 @@
+const { PIDController } = require('./index');
+
+console.log('=== PID CONTROLLER EXAMPLES ===\n');
+console.log('This guide shows how to instantiate, tune, and operate the PID helper.\n');
+
+// ====================================
+// EXAMPLE 1: FLOW CONTROL LOOP
+// ====================================
+console.log('--- Example 1: Pump speed control ---');
+
+const pumpController = new PIDController({
+  kp: 1.1,
+  ki: 0.35,
+  kd: 0.08,
+  sampleTime: 250, // ms
+  outputMin: 0,
+  outputMax: 100,
+  derivativeFilter: 0.2
+});
+
+const pumpSetpoint = 75; // desired flow percentage
+let pumpFlow = 20;
+const pumpStart = Date.now();
+
+for (let i = 0; i < 10; i += 1) {
+  const timestamp = pumpStart + (i + 1) * pumpController.sampleTime;
+  const controlSignal = pumpController.update(pumpSetpoint, pumpFlow, timestamp);
+
+  // Simple first-order plant approximation
+  pumpFlow += (controlSignal - pumpFlow) * 0.12;
+  pumpFlow -= (pumpFlow - pumpSetpoint) * 0.05; // disturbance rejection
+
+  console.log(
+    `Cycle ${i + 1}: output=${controlSignal.toFixed(2)}% | flow=${pumpFlow.toFixed(2)}%`
+  );
+}
+
+console.log('Pump loop state:', pumpController.getState(), '\n');
+
+// ====================================
+// EXAMPLE 2: TANK LEVEL WITH MANUAL/AUTO
+// ====================================
+console.log('--- Example 2: Tank level handover ---');
+
+const tankController = new PIDController({
+  kp: 2.0,
+  ki: 0.5,
+  kd: 0.25,
+  sampleTime: 400,
+  derivativeFilter: 0.25,
+  outputMin: 0,
+  outputMax: 1
+}).setIntegralLimits(-0.3, 0.3);
+
+tankController.setMode('manual');
+tankController.setManualOutput(0.4);
+console.log(`Manual output locked at ${tankController.getLastOutput().toFixed(2)}\n`);
+
+tankController.setMode('automatic');
+
+let level = 0.2;
+const levelSetpoint = 0.8;
+const tankStart = Date.now();
+
+for (let step = 0; step < 8; step += 1) {
+  const timestamp = tankStart + (step + 1) * tankController.sampleTime;
+  const output = tankController.update(levelSetpoint, level, timestamp);
+
+  // Integrating process with slight disturbance
+  level += (output - 0.5) * 0.18;
+  level += 0.02; // inflow bump
+  level = Math.max(0, Math.min(1, level));
+
+  console.log(
+    `Cycle ${step + 1}: output=${output.toFixed(3)} | level=${level.toFixed(3)}`
+  );
+}
+
+console.log('\nBest practice tips:');
+console.log('  - Call update() on a fixed interval (sampleTime).');
+console.log('  - Clamp output and integral to avoid windup.');
+console.log('  - Use setMode("manual") during maintenance or bump-less transfer.');
+
+module.exports = {
+  pumpController,
+  tankController
+};

src/pid/index.js

@@ -0,0 +1,14 @@
+const { PIDController, CascadePIDController } = require('./PIDController');
+
+/**
+ * Convenience factories.
+ */
+const createPidController = (options) => new PIDController(options);
+const createCascadePidController = (options) => new CascadePIDController(options);
+
+module.exports = {
+  PIDController,
+  CascadePIDController,
+  createPidController,
+  createCascadePidController,
+};

src/predict/index.js

@@ -0,0 +1,9 @@
+const predict = require('./predict_class.js');
+const interpolation = require('./interpolation.js');
+const predictConfig = require('./predictConfig.json');
+
+module.exports = {
+  predict,
+  interpolation,
+  predictConfig,
+};

src/predict/predict_class.js

@@ -68,10 +68,25 @@ const Interpolation = require('./interpolation');
 class Predict {
   constructor(config = {}) {
 
+    // Capture share-source BEFORE config validation strips it (ConfigUtils
+    // mutates the input config to drop unknown keys, which would remove
+    // shareInputsFrom because it's not in predictConfig.json's schema).
+    // Detach on a shallow clone so validateSchema doesn't see the key at all
+    // — leaving it on the input would emit a `[interpolation] Unknown key
+    // 'shareInputsFrom'` warning per group-predictor on every curve refresh.
+    const _sharedSource = (config && config.shareInputsFrom instanceof Predict)
+      ? config.shareInputsFrom
+      : null;
+    let _initConfig = config;
+    if (_initConfig && 'shareInputsFrom' in _initConfig) {
+      _initConfig = { ..._initConfig };
+      delete _initConfig.shareInputsFrom;
+    }
+
     // Initialize dependencies
     this.emitter = new EventEmitter();  // Own EventEmitter
     this.configUtils = new ConfigUtils(defaultConfig);
-    this.config = this.configUtils.initConfig(config);
+    this.config = this.configUtils.initConfig(_initConfig);
 
     // Init after config is set
     this.logger = new Logger(this.config.general.logging.enabled,this.config.general.logging.logLevel, this.config.general.name);
@@ -107,8 +122,29 @@ class Predict {
     this.calculationPoints = this.config.normalization.parameters.curvePoints;
     this.interpolationType = this.config.interpolation.type;
 
-    // Load curve if provided
-    if (config.curve) {
+    // Load curve if provided.
+    //   shareInputsFrom: an existing Predict instance whose pre-built input
+    //   curves and splines we adopt by reference. Used to create a parallel
+    //   "view" of the same source curves (e.g. an MGC group-scope predict
+    //   that mirrors a pump's individual predict). Per-instance state —
+    //   currentF / currentX / currentFxyCurve / currentFxySplines /
+    //   currentFxyY/X Min/Max / outputY — stays freshly initialised so the
+    //   two views have independent operating points. Curve mutations on the
+    //   source via updateCurve() are propagated through the source's
+    //   "curveUpdated" emitter (see updateCurve below).
+    if (_sharedSource) {
+      this._adoptInputsFrom(_sharedSource);
+      this._sharedInputsSource = _sharedSource;
+      this._sharedInputsHandler = (newCurve) => {
+        this._adoptInputsFrom(this._sharedInputsSource);
+        // Keep our currentF in range; constrain re-uses the new fValues.
+        this.fDimension = this.constrain(this.currentF, this.fValues.min, this.fValues.max);
+      };
+      this._sharedInputsSource.emitter.on('curveUpdated', this._sharedInputsHandler);
+      // Initialise our own operating point to the source's min, same as
+      // the standard buildAllFxyCurves flow does at end of curve load.
+      this.fDimension = this.fValues.min;
+    } else if (config.curve) {
       this.inputCurveData = config.curve;
     } else {
       this.logger.warn("No curve data provided. Please set curve data using setCurveData method. Using default");
@@ -116,6 +152,31 @@ class Predict {
     }
 
   }
+
+  // Adopt another Predict's input curves and splines by reference. Used by
+  // the shareInputsFrom constructor option and by the curveUpdated emitter
+  // handler to re-sync after the source's curves change. Does NOT touch
+  // per-instance state (currentF, currentX, currentFxy* etc.).
+  //
+  // Also copies the scalar parameters (calculationPoints, normMin/Max,
+  // interpolationType) so the clone uses the SAME pointsCount the source
+  // built fSplines with — otherwise buildSingleFxyCurve can iterate past
+  // the end of the shared fSplines.
+  _adoptInputsFrom(source) {
+    this.inputCurve        = source.inputCurve;
+    this.normalizedCurve   = source.normalizedCurve;
+    this.calculatedCurve   = source.calculatedCurve;
+    this.fCurve            = source.fCurve;
+    this.fSplines          = source.fSplines;
+    this.normalizedSplines = source.normalizedSplines;
+    this.xValues           = source.xValues;
+    this.fValues           = source.fValues;
+    this.yValues           = source.yValues;
+    this.calculationPoints = source.calculationPoints;
+    this.normMin           = source.normMin;
+    this.normMax           = source.normMax;
+    this.interpolationType = source.interpolationType;
+  }
   
   // Improved function to get a local peak in an array by starting in the middle.
   // It also handles the case of a tie by preferring the left side (arbitrary choice)
@@ -348,6 +409,9 @@ class Predict {
 
     this.buildAllFxyCurves(validatedCurve);
 
+    // Notify shared-input clones (see shareInputsFrom in the constructor).
+    // They re-adopt our inputs and clamp their own operating point.
+    this.emitter.emit('curveUpdated', validatedCurve);
   }
 
   constrain(value,min,max) {

src/registry/AssetResolver.js

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * AssetResolver — single entry point for all asset-side metadata in EVOLV.
+ *
+ * Namespaces are declared at construction (see ./namespaces/*). Each namespace
+ * exposes a `loadAll()` returning a `Map<id, payload>`; AssetResolver routes
+ * resolve(name, id) calls into the right namespace, caches the loaded map, and
+ * exposes async `refresh(name?)` for future HttpBackend hydration.
+ *
+ * Resolution is sync by contract: the first resolve() for an unwarmed
+ * namespace pulls everything into cache, all subsequent calls are O(1).
+ *
+ * Backend abstraction (./backends/*) is where File vs Http lives — namespaces
+ * just hold a backend reference and call backend.loadAll().
+ *
+ * See ./README.md for the full extension story.
+ */
+
+class AssetResolver {
+    constructor(namespaces = []) {
+        this._slots = new Map();
+        for (const ns of namespaces) {
+            if (!ns || !ns.name || typeof ns.loadAll !== 'function') {
+                throw new TypeError('AssetResolver: namespace must declare { name, loadAll() }');
+            }
+            this._slots.set(ns.name, { ns, cache: null });
+        }
+    }
+
+    _ensureWarm(name) {
+        const slot = this._slots.get(name);
+        if (!slot) throw new Error(`AssetResolver: unknown namespace '${name}'`);
+        if (slot.cache === null) slot.cache = slot.ns.loadAll();
+        return slot;
+    }
+
+    resolve(namespace, id) {
+        const slot = this._ensureWarm(namespace);
+        const key = String(id ?? '').toLowerCase();
+        if (!key) return null;
+        return slot.cache.get(key) ?? null;
+    }
+
+    list(namespace) {
+        const slot = this._ensureWarm(namespace);
+        return [...slot.cache.keys()];
+    }
+
+    namespaces() {
+        return [...this._slots.keys()];
+    }
+
+    async refresh(namespace) {
+        if (namespace) {
+            const slot = this._slots.get(namespace);
+            if (!slot) throw new Error(`AssetResolver: unknown namespace '${namespace}'`);
+            slot.cache = typeof slot.ns.refresh === 'function'
+                ? await slot.ns.refresh()
+                : slot.ns.loadAll();
+            return;
+        }
+        for (const slot of this._slots.values()) {
+            slot.cache = typeof slot.ns.refresh === 'function'
+                ? await slot.ns.refresh()
+                : slot.ns.loadAll();
+        }
+    }
+
+    /**
+     * Cross-namespace helper: given a softwareType + model id, walk the
+     * editor menu tree to return { supplier, type, units, raw } so domain
+     * code doesn't have to persist supplier/type/unit on the node.
+     */
+    resolveAssetMetadata(softwareType, modelId) {
+        if (!softwareType || !modelId) return null;
+        const tree = this.resolve('menu', softwareType);
+        if (!tree || !Array.isArray(tree.suppliers)) return null;
+        const norm = String(modelId).toLowerCase();
+        for (const supplier of tree.suppliers) {
+            for (const type of supplier.types || []) {
+                for (const model of type.models || []) {
+                    const candidate = String(model.id || model.name || '').toLowerCase();
+                    if (candidate === norm) {
+                        return {
+                            supplier:   supplier.name,
+                            supplierId: supplier.id || supplier.name,
+                            type:       type.name,
+                            typeId:     type.id || type.name,
+                            model:      model.name,
+                            modelId:    model.id || model.name,
+                            units:      Array.isArray(model.units) ? [...model.units] : [],
+                            raw:        model,
+                        };
+                    }
+                }
+            }
+        }
+        return null;
+    }
+}
+
+module.exports = AssetResolver;

src/registry/README.md

@@ -0,0 +1,78 @@
+# registry — AssetResolver
+
+Single entry point for all asset-side metadata: pump/valve curves, editor menu
+trees, monster sample codes, unit families, and anything else we add later.
+
+Replaces (will replace, phase-by-phase):
+
+- `loadCurve(model)` → `assetResolver.resolve('curves', model)`
+- `AssetCategoryManager` → `assetResolver.resolve('menu', softwareType)`
+- ad-hoc loaders for `monsterSamples.json`, `unitData.json` → `assetResolver.resolve('monsterSamples'|'units', …)`
+
+## Surface
+
+```js
+const { assetResolver } = require('generalFunctions');
+
+const curve = assetResolver.resolve('curves', 'hidrostal-H05K-S03R');
+const tree  = assetResolver.resolve('menu',   'rotatingmachine');
+const meta  = assetResolver.resolveAssetMetadata('rotatingmachine', 'hidrostal-H05K-S03R');
+// meta → { supplier, type, units, model, raw }
+
+assetResolver.list('curves');       // ['hidrostal-H05K-S03R', 'ECDV', ...]
+assetResolver.namespaces();         // ['curves', 'menu', 'monsterSamples', 'units']
+await assetResolver.refresh();      // re-pull everything (FileBackend: re-reads disk; HttpBackend: future)
+```
+
+Resolution is synchronous. First call to `resolve(namespace, id)` warms that
+namespace's cache; later calls are O(1) map lookups.
+
+## Adding a namespace
+
+Create `src/registry/namespaces/<name>.js`:
+
+```js
+const path = require('path');
+const FileBackend = require('../backends/FileBackend');
+
+const backend = new FileBackend({
+    baseDir: path.resolve(__dirname, '../../../datasets/...'),
+    layout: 'per-id',           // or 'single-file'
+    caseInsensitive: true,
+});
+
+module.exports = {
+    name: 'newThing',
+    description: 'What this namespace is for',
+    loadAll: () => backend.loadAll(),
+    refresh: () => backend.refresh(),
+};
+```
+
+Register it in `namespaces/index.js`. Done.
+
+## Backends
+
+- **FileBackend** — reads JSON from disk. Two layouts: `per-id` (one file per
+  id, filename minus `.json` is the id) or `single-file` (one file with an
+  array; pick `arrayKey` and `indexField`).
+- **HttpBackend** — stub. Disabled unless `EVOLV_ASSET_REMOTE=1`. Will hold
+  the future WBD product API client; currently throws if invoked. Exists so
+  the resolver contract is backend-agnostic from day one.
+
+Backends are interchangeable per namespace: the namespace file is the
+declarative join between "what this metadata is" and "where it comes from".
+
+## Why sync at runtime
+
+Node-RED node constructors aren't async-friendly. Every consumer that used
+`loadCurve(model)` expects a synchronous return. The resolver preserves that
+contract: cache is warmed lazily (first `resolve()` call pulls everything),
+and lookups are O(1) map gets after that. Async `refresh()` exists for future
+HttpBackend hydration on a background timer.
+
+## Convention: namespace name is the cache key
+
+`assetResolver.resolve(namespace, id)` lowercases `id` for the lookup. Old
+case-mismatched configs (`Hidrostal-H05K-S03R` vs `hidrostal-H05K-S03R`) still
+resolve correctly — same as `loadCurve` did historically.

src/registry/backends/FileBackend.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * FileBackend — reads JSON payloads from a directory on disk.
+ *
+ * Two layouts supported:
+ *   - 'per-id'      one file per id (filename minus .json is the id)
+ *   - 'single-file' one file containing an array; index by a field name
+ *
+ * Returns Map<lowerCaseId, payload>. Case-insensitive lookups by default —
+ * matches how loadCurve worked historically.
+ */
+class FileBackend {
+    constructor(opts = {}) {
+        const {
+            baseDir,
+            layout = 'per-id',
+            filePath,
+            arrayKey,
+            indexField,
+            exclude = [],
+            caseInsensitive = true,
+        } = opts;
+
+        if (!baseDir) throw new TypeError('FileBackend: baseDir is required');
+        if (layout !== 'per-id' && layout !== 'single-file') {
+            throw new TypeError(`FileBackend: unsupported layout '${layout}'`);
+        }
+        if (layout === 'single-file' && !filePath) {
+            throw new TypeError('FileBackend: single-file layout requires filePath');
+        }
+
+        this.baseDir = baseDir;
+        this.layout = layout;
+        this.filePath = filePath;
+        this.arrayKey = arrayKey;
+        this.indexField = indexField;
+        this.exclude = new Set(exclude);
+        this.caseInsensitive = caseInsensitive;
+    }
+
+    _norm(k) {
+        return this.caseInsensitive ? String(k).toLowerCase() : String(k);
+    }
+
+    loadAll() {
+        if (this.layout === 'per-id') return this._loadPerId();
+        return this._loadSingleFile();
+    }
+
+    async refresh() {
+        // No actual I/O penalty on local disk; the async surface exists so
+        // callers can `await resolver.refresh()` symmetrically with future
+        // HttpBackend implementations.
+        return this.loadAll();
+    }
+
+    _loadPerId() {
+        const map = new Map();
+        if (!fs.existsSync(this.baseDir)) return map;
+        const entries = fs.readdirSync(this.baseDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile()) continue;
+            if (!entry.name.endsWith('.json')) continue;
+            const id = path.basename(entry.name, '.json');
+            if (this.exclude.has(id)) continue;
+            const raw = fs.readFileSync(path.join(this.baseDir, entry.name), 'utf8');
+            const data = JSON.parse(raw);
+            map.set(this._norm(id), data);
+        }
+        return map;
+    }
+
+    _loadSingleFile() {
+        const full = path.resolve(this.baseDir, this.filePath);
+        if (!fs.existsSync(full)) return new Map();
+        const data = JSON.parse(fs.readFileSync(full, 'utf8'));
+        const arr = this.arrayKey ? data[this.arrayKey] : data;
+        if (!Array.isArray(arr)) {
+            throw new Error(
+                `FileBackend(single-file): expected array at ${this.arrayKey || '<root>'} in ${full}`,
+            );
+        }
+        const map = new Map();
+        for (const entry of arr) {
+            const k = entry && this.indexField ? entry[this.indexField] : null;
+            if (k != null) map.set(this._norm(k), entry);
+        }
+        return map;
+    }
+}
+
+module.exports = FileBackend;

src/registry/backends/HttpBackend.js

@@ -0,0 +1,41 @@
+'use strict';
+
+/**
+ * HttpBackend — stub. The shape that any future remote product/asset DB will
+ * implement so the resolver can swap backends without touching consumers.
+ *
+ * Disabled by default. Set EVOLV_ASSET_REMOTE=1 to opt in; even then this
+ * stub throws on use because the upstream API is not yet defined. See
+ * `assetApiConfig.js` for the URL/auth scaffolding that will eventually
+ * land here.
+ */
+class HttpBackend {
+    constructor({ url, headers = {}, namespace } = {}) {
+        this.url = url;
+        this.headers = headers;
+        this.namespace = namespace;
+    }
+
+    static get enabled() {
+        return process.env.EVOLV_ASSET_REMOTE === '1';
+    }
+
+    loadAll() {
+        if (!HttpBackend.enabled) {
+            throw new Error(
+                'HttpBackend disabled (set EVOLV_ASSET_REMOTE=1 to enable); ' +
+                'no synchronous remote fetch is implemented yet.',
+            );
+        }
+        throw new Error(
+            'HttpBackend.loadAll(): remote asset backend not yet implemented. ' +
+            'Use FileBackend or implement this method against the WBD product API.',
+        );
+    }
+
+    async refresh() {
+        return this.loadAll();
+    }
+}
+
+module.exports = HttpBackend;

src/registry/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const AssetResolver = require('./AssetResolver');
+const FileBackend   = require('./backends/FileBackend');
+const HttpBackend   = require('./backends/HttpBackend');
+const namespaces    = require('./namespaces');
+
+const assetResolver = new AssetResolver(namespaces);
+
+module.exports = {
+    AssetResolver,
+    FileBackend,
+    HttpBackend,
+    assetResolver,
+};

src/registry/namespaces/curves.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const path = require('path');
+const FileBackend = require('../backends/FileBackend');
+
+const backend = new FileBackend({
+    baseDir: path.resolve(__dirname, '../../../datasets/assetData/curves'),
+    layout: 'per-id',
+    caseInsensitive: true,
+});
+
+module.exports = {
+    name: 'curves',
+    description: 'Pump and valve performance curves keyed by model id',
+    loadAll: () => backend.loadAll(),
+    refresh: () => backend.refresh(),
+};

src/registry/namespaces/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+module.exports = [
+    require('./curves'),
+    require('./menu'),
+    require('./monsterSamples'),
+    require('./monsterSpecs'),
+    require('./units'),
+];

src/registry/namespaces/menu.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const FileBackend = require('../backends/FileBackend');
+
+const BASE_DIR = path.resolve(__dirname, '../../../datasets/assetData');
+// Files in datasets/assetData that aren't editor menu trees.
+const EXCLUDE = ['assetData', 'monsterSamples', 'unitData'];
+
+// Plain per-id File backend, but the menu namespace also wants to key by the
+// inner `softwareType` field (so '/menu/rotatingmachine' works even if the
+// file is named machine.json). The FileBackend gives us filename-keyed maps;
+// we rekey in a thin wrapper.
+const backend = new FileBackend({
+    baseDir: BASE_DIR,
+    layout: 'per-id',
+    caseInsensitive: true,
+    exclude: EXCLUDE,
+});
+
+// Menu trees are looked up by softwareType. We index by BOTH the inner
+// `softwareType` field AND the filename (sans .json), because consumers come
+// from two paths: editor endpoints pass the node type ('rotatingmachine'),
+// while older code paths pass the filename slug ('machine'). Both should hit
+// the same tree.
+function _rekeyBySoftwareType(map) {
+    const out = new Map();
+    for (const [filenameId, data] of map.entries()) {
+        const stKey = String(data?.softwareType || '').toLowerCase();
+        const fnKey = String(filenameId).toLowerCase();
+        if (stKey) out.set(stKey, data);
+        if (fnKey && fnKey !== stKey) out.set(fnKey, data);
+    }
+    return out;
+}
+
+module.exports = {
+    name: 'menu',
+    description: 'Editor cascade trees (supplier→type→model→unit), keyed by softwareType',
+    loadAll: () => _rekeyBySoftwareType(backend.loadAll()),
+    refresh: async () => _rekeyBySoftwareType(await backend.refresh()),
+    // Exposed for inline tests / debugging.
+    _BASE_DIR: BASE_DIR,
+    _EXCLUDE: EXCLUDE,
+    _existsForFilename: (id) => fs.existsSync(path.join(BASE_DIR, `${id}.json`)),
+};

src/registry/namespaces/monsterSamples.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const path = require('path');
+const FileBackend = require('../backends/FileBackend');
+
+const backend = new FileBackend({
+    baseDir: path.resolve(__dirname, '../../../datasets/assetData'),
+    layout: 'single-file',
+    filePath: 'monsterSamples.json',
+    arrayKey: 'samples',
+    indexField: 'code',
+    caseInsensitive: true,
+});
+
+module.exports = {
+    name: 'monsterSamples',
+    description: 'Monster (Aquon) sample codes keyed by sample code',
+    loadAll: () => backend.loadAll(),
+    refresh: () => backend.refresh(),
+};

src/registry/namespaces/monsterSpecs.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// monsterSpecs is a single-document namespace (one file, two top-level keys:
+// defaults and bySample). It doesn't fit FileBackend's per-id or single-file
+// array layouts cleanly — so we inline a tiny loader here instead of bending
+// FileBackend to accommodate the shape.
+//
+// The whole document is exposed under id 'all'. Consumers (AquonSamplesMenu,
+// monster specificClass) call assetResolver.resolve('monsterSpecs', 'all').
+
+const FILE_PATH = path.resolve(__dirname, '../../../datasets/assetData/specs/monster/index.json');
+
+function _load() {
+    if (!fs.existsSync(FILE_PATH)) return new Map();
+    const data = JSON.parse(fs.readFileSync(FILE_PATH, 'utf8'));
+    return new Map([['all', {
+        defaults: data.defaults || {},
+        bySample: data.bySample || {},
+    }]]);
+}
+
+module.exports = {
+    name: 'monsterSpecs',
+    description: 'Monster sampling specs (defaults + per-sample overrides) from specs/monster/index.json',
+    loadAll: _load,
+    refresh: () => _load(),
+};

src/registry/namespaces/units.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const path = require('path');
+const FileBackend = require('../backends/FileBackend');
+
+// unitData.json lives at datasets/ (not datasets/assetData/).
+const backend = new FileBackend({
+    baseDir: path.resolve(__dirname, '../../../datasets'),
+    layout: 'single-file',
+    filePath: 'unitData.json',
+    arrayKey: 'units',
+    indexField: 'category',
+    caseInsensitive: true,
+});
+
+module.exports = {
+    name: 'units',
+    description: 'Unit families keyed by measurement category (flow, pressure, …)',
+    loadAll: () => backend.loadAll(),
+    refresh: () => backend.refresh(),
+};

src/state/index.js

@@ -0,0 +1,11 @@
+const state = require('./state.js');
+const stateManager = require('./stateManager.js');
+const movementManager = require('./movementManager.js');
+const stateConfig = require('./stateConfig.json');
+
+module.exports = {
+  state,
+  stateManager,
+  movementManager,
+  stateConfig,
+};

src/state/movementManager.js

@@ -13,12 +13,12 @@ class movementManager {
 
     this.speed = speed;
     this.maxSpeed = maxSpeed;
-      console.log(`MovementManager: Initial speed=${this.speed}, maxSpeed=${maxSpeed}`);
     this.interval = interval;
     this.timeleft = 0; // timeleft of current movement
 
     this.logger = logger;
     this.movementMode = config.movement.mode;
+    this.logger?.debug?.(`MovementManager initialized: speed=${this.speed}, maxSpeed=${this.maxSpeed}`);
   }
 
   getCurrentPosition() {
@@ -79,68 +79,70 @@ class movementManager {
     // Clamp the final target into [minPosition, maxPosition]
     targetPosition = this.constrain(targetPosition);
 
-    // Compute direction and remaining distance
-    const direction = targetPosition > this.currentPosition ? 1 : -1;
-    const distance  = Math.abs(targetPosition - this.currentPosition);
+    // Snapshot the starting point. Position is derived from ELAPSED WALL-TIME
+    // (not accumulated per-tick steps) so an interruption that lands between
+    // ticks — or before the very first tick — still leaves currentPosition at
+    // the real distance travelled. A fast re-commanding parent (e.g. MGC
+    // updating demand every tick) then re-bases from the true position instead
+    // of freezing at the start. See _settleAt / the abort handler below.
+    const startPosition = this.currentPosition;
+    const direction = targetPosition > startPosition ? 1 : -1;
+    const distance  = Math.abs(targetPosition - startPosition);
 
-    // Speed is a fraction [0,1] of full-range per second
-    this.speed = Math.min(Math.max(this.speed, 0), 1);
-    const fullRange = this.maxPosition - this.minPosition;
-    const velocity  = this.speed * fullRange;      // units per second
-    if (velocity === 0) {
+    const velocity = this.getVelocity(); // units per second
+    if (velocity <= 0) {
       return reject(new Error("Movement aborted: zero speed"));
     }
 
-    // Duration and bookkeeping
-    const duration   = distance / velocity;        // seconds to go the remaining distance
-    this.timeleft    = duration;
+    const duration  = distance / velocity;        // seconds to go the full distance
+    this.timeleft   = duration;
     this.logger.debug(
       `Linear move: dir=${direction}, dist=${distance}, vel=${velocity.toFixed(2)} u/s, dur=${duration.toFixed(2)}s`
     );
 
-    // Compute how much to move each tick
-    const intervalMs   = this.interval;
-    const intervalSec  = intervalMs / 1000;
-    const stepSize     = direction * velocity * intervalSec;
+    const intervalMs = this.interval;
+    const startTime  = Date.now();
 
-    const startTime = Date.now();
+    // Position reached after `elapsedSec` of travel, clamped to the target.
+    const posAt = (elapsedSec) =>
+      this.constrain(startPosition + direction * Math.min(distance, velocity * elapsedSec));
+    // Re-base currentPosition (and timeleft) onto the real elapsed progress.
+    const settle = () => {
+      const elapsed = (Date.now() - startTime) / 1000;
+      this.currentPosition = posAt(elapsed);
+      this.timeleft = Math.max(0, duration - elapsed);
+      this.emitPos(this.currentPosition);
+      return elapsed;
+    };
 
     // Kick off the loop
     const intervalId = setInterval(() => {
-      // 7a) Abort check
       if (signal?.aborted) {
         clearInterval(intervalId);
+        settle();
         return reject(new Error("Movement aborted"));
       }
 
-      //  Advance position and clamp
-      this.currentPosition += stepSize;
-      this.currentPosition = this.constrain(this.currentPosition);
-      this.emitPos(this.currentPosition);
-
-      // Update timeleft
-      const elapsed = (Date.now() - startTime) / 1000;
-      this.timeleft  = Math.max(0, duration - elapsed);
-
+      const elapsed = settle();
       this.logger.debug(
         `pos=${this.currentPosition.toFixed(2)}, timeleft=${this.timeleft.toFixed(2)}`
       );
 
-      // Completed the move?
-      if (
-        (direction > 0 && this.currentPosition >= targetPosition) ||
-        (direction < 0 && this.currentPosition <= targetPosition)
-      ) {
+      // Completed the move? (time-based so it can't overshoot/undershoot)
+      if (elapsed >= duration) {
         clearInterval(intervalId);
         this.currentPosition = targetPosition;
+        this.timeleft = 0;
         this.emitPos(this.currentPosition);
         return resolve("Reached target move.");
       }
     }, intervalMs);
 
-    // 8) Also catch aborts that happen before the first tick
+    // Catch aborts that happen between ticks (incl. before the first tick):
+    // capture the partial progress so the move re-bases instead of freezing.
     signal?.addEventListener("abort", () => {
       clearInterval(intervalId);
+      settle();
       reject(new Error("Movement aborted"));
     });
   });
@@ -156,11 +158,11 @@ class movementManager {
       const direction = targetPosition > this.currentPosition ? 1 : -1;
       const distance = Math.abs(targetPosition - this.currentPosition);
 
-      // Ensure speed is a percentage [0, 1]
-      this.speed = Math.min(Math.max(this.speed, 0), 1);
-
-      // Calculate duration based on percentage of distance per second
-      const duration = 1 / this.speed; // 1 second for 100% of the distance
+      const velocity = this.getVelocity();
+      if (velocity <= 0) {
+        return reject(new Error("Movement aborted: zero speed"));
+      }
+      const duration = distance / velocity;
 
       this.timeleft = duration; //set this so other classes can use it
       this.logger.debug(
@@ -216,52 +218,63 @@ class movementManager {
         return reject(new Error("Movement aborted"));
       }
 
-      const totalDistance = Math.abs(targetPosition - this.currentPosition);
       const startPosition = this.currentPosition;
-      this.speed = Math.min(Math.max(this.speed, 0), 1);
+      const totalDistance = Math.abs(targetPosition - this.currentPosition);
+      const velocity = this.getVelocity();
+      if (velocity <= 0) {
+        return reject(new Error("Movement aborted: zero speed"));
+      }
 
       const easeFunction = (t) =>
         t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
 
-      let elapsedTime = 0;
-      const duration = totalDistance / this.speed;
+      const duration = totalDistance / velocity;
       this.timeleft = duration;
       const interval = this.interval;
+      const startTime = Date.now();
+
+      // Position from ELAPSED WALL-TIME (eased), so an interruption between
+      // ticks re-bases from the real position rather than freezing at the
+      // start — same rationale as moveLinear.
+      const posAt = (elapsedSec) => {
+        const progress = duration > 0 ? Math.min(elapsedSec / duration, 1) : 1;
+        return startPosition + (targetPosition - startPosition) * easeFunction(progress);
+      };
+      const settle = () => {
+        const elapsed = (Date.now() - startTime) / 1000;
+        this.currentPosition = posAt(elapsed);
+        this.timeleft = Math.max(0, duration - elapsed);
+        this.emitPos(this.currentPosition);
+        return elapsed;
+      };
 
       // 2) Start the moving loop
       const intervalId = setInterval(() => {
         // 3) Check for abort on each tick
         if (signal?.aborted) {
           clearInterval(intervalId);
+          settle();
           return reject(new Error("Movement aborted"));
         }
 
-        elapsedTime += interval / 1000;
-        const progress = Math.min(elapsedTime / duration, 1);
-        this.timeleft = duration - elapsedTime;
-        const easedProgress = easeFunction(progress);
-        const newPosition =
-          startPosition + (targetPosition - startPosition) * easedProgress;
-
-        this.emitPos(newPosition);
+        const elapsed = settle();
         this.logger.debug(
-          `Using ${this.movementMode} => Progress=${progress.toFixed(
-            2
-          )}, Eased=${easedProgress.toFixed(2)}`
+          `Using ${this.movementMode} => elapsed=${elapsed.toFixed(2)}s, pos=${this.currentPosition.toFixed(2)}`
         );
 
-        if (progress >= 1) {
+        if (elapsed >= duration) {
           clearInterval(intervalId);
           this.currentPosition = targetPosition;
+          this.timeleft = 0;
+          this.emitPos(this.currentPosition);
           resolve(`Reached target move.`);
-        } else {
-          this.currentPosition = newPosition;
         }
       }, interval);
 
-      // 4) Also listen once for abort before first tick
+      // 4) Capture partial progress on aborts between/before ticks.
       signal?.addEventListener("abort", () => {
         clearInterval(intervalId);
+        settle();
         reject(new Error("Movement aborted"));
       });
     });
@@ -274,6 +287,20 @@ class movementManager {
   constrain(value) {
     return Math.min(Math.max(value, this.minPosition), this.maxPosition);
   }
+
+  getNormalizedSpeed() {
+    const rawSpeed = Number.isFinite(this.speed) ? this.speed : 0;
+    const clampedSpeed = Math.max(0, rawSpeed);
+    const hasMax = Number.isFinite(this.maxSpeed) && this.maxSpeed > 0;
+    const effectiveSpeed = hasMax ? Math.min(clampedSpeed, this.maxSpeed) : clampedSpeed;
+    return effectiveSpeed / 100; // convert %/s -> fraction of range per second
+  }
+
+  getVelocity() {
+    const normalizedSpeed = this.getNormalizedSpeed();
+    const fullRange = this.maxPosition - this.minPosition;
+    return normalizedSpeed * fullRange;
+  }
 }
 
 module.exports = movementManager;

src/state/state.js

@@ -23,6 +23,13 @@ class state{
 
     this.delayedMove = null;
     this.mode = this.config.mode.current;
+    // Monotonic counter incremented on every EXTERNAL abort (i.e. one
+    // initiated outside the in-flight sequence — typically MGC reacting
+    // to a new demand). executeSequence captures the value at entry and
+    // breaks its for-loop if the counter advances mid-sequence, so a
+    // shutdown that was already past its ramp-down step doesn't barge
+    // through stopping → coolingdown when a re-engage arrives.
+    this.sequenceAbortToken = 0;
 
     // Log initialization
     this.logger.info("State class initialized.");
@@ -52,7 +59,11 @@ class state{
     return this.stateManager.getRunTimeHours();
   }
 
+  getMaintenanceTimeHours(){
+    return this.stateManager.getMaintenanceTimeHours();
+  }
 
+ 
   async moveTo(targetPosition) {
 
     // Check for invalid conditions and throw errors
@@ -62,15 +73,41 @@ class state{
     }
 
     if (this.stateManager.getCurrentState() !== "operational") {
-      if (this.config.mode.current === "auto") {
-        this.delayedMove = targetPosition;
-        this.logger.warn(`Saving setpoint=${targetPosition} to execute once back in 'operational' state.`);
+      // 'accelerating' / 'decelerating' here is post-abort residue —
+      // the previous moveTo was aborted (e.g. MGC's per-tick
+      // abortActiveMovements) and the catch block intentionally
+      // doesn't auto-return to operational (avoids a bounce loop).
+      // BUT a new setpoint just arrived, so there's nothing for the
+      // anti-bounce policy to protect: the caller IS asking for a
+      // move. Fall through to operational and execute it. Without
+      // this the FSM gets parked, all subsequent setpoints land in
+      // delayedMove which never fires, and currentPosition freezes —
+      // see test/integration/abort-deadlock.integration.test.js for
+      // the exact deadlock scenario.
+      const movementResidueStates = ['accelerating', 'decelerating'];
+      if (movementResidueStates.includes(this.stateManager.getCurrentState())) {
+        this.logger.debug(`moveTo(${targetPosition}) arrived while parked in '${this.stateManager.getCurrentState()}' (post-abort). Returning to operational to service the new setpoint.`);
+        try {
+          await this.transitionToState("operational");
+        } catch (e) {
+          this.logger.warn(`Could not transition out of '${this.stateManager.getCurrentState()}': ${e?.message || e}`);
+          return;
+        }
+        // Fall through — state is now operational, proceed with new move.
+      } else {
+        // Genuine non-operational state (starting, warmingup, stopping,
+        // coolingdown, idle, off, emergencystop, maintenance) — these
+        // are sequence steps the caller can't legitimately interrupt
+        // with a setpoint. Save for later, exactly as before.
+        if (this.config.mode.current === "auto") {
+          this.delayedMove = targetPosition;
+          this.logger.warn(`Saving setpoint=${targetPosition} to execute once back in 'operational' state.`);
+        }
+        else{
+          this.logger.warn(`Not able to accept setpoint=${targetPosition} while not in ${this.stateManager.getCurrentState()} state`);
+        }
+        return;
       }
-      else{
-        this.logger.warn(`Not able to accept setpoint=${targetPosition} while not in ${this.stateManager.getCurrentState()} state`);
-      }
-      //return early
-      return;
     }
     this.abortController = new AbortController();
     const { signal } = this.abortController;
@@ -81,15 +118,54 @@ class state{
       this.emitter.emit("movementComplete", { position: targetPosition });
       await this.transitionToState("operational");
     } catch (error) {
-      this.logger.error(error);
+      // Abort path: only return to 'operational' when explicitly requested
+      // (shutdown/emergency-stop needs it to unblock the FSM). Routine MGC
+      // demand-update aborts must NOT auto-transition — doing so causes a
+      // bounce loop where every tick aborts → operational → new move →
+      // abort → operational → ... and the pump never reaches its setpoint.
+      const msg = typeof error === 'string' ? error : error?.message;
+      if (msg === 'Transition aborted' || msg === 'Movement aborted') {
+        if (this._returnToOperationalOnAbort) {
+          this.logger.debug(`Movement aborted; returning to 'operational' (requested by caller).`);
+          try {
+            await this.transitionToState("operational");
+          } catch (e) {
+            this.logger.debug(`Post-abort transition to operational failed: ${e?.message || e}`);
+          }
+        } else {
+          this.logger.debug(`Movement aborted; staying in current state (routine abort).`);
+        }
+        this._returnToOperationalOnAbort = false;
+        this.emitter.emit("movementAborted", { position: targetPosition });
+      } else {
+        this.logger.error(error);
+      }
     }
   }
   
   // -------- State Transition Methods -------- //
 
-  abortCurrentMovement(reason = "group override") {
+  /**
+   * @param {string} reason - human-readable abort reason
+   * @param {object} [options]
+   * @param {boolean} [options.returnToOperational=false] - when true the FSM
+   *   transitions back to 'operational' after the abort so a subsequent
+   *   shutdown/emergency-stop sequence can proceed. Set to false (default)
+   *   for routine demand updates where the caller will send a new movement
+   *   immediately — auto-transitioning would cause a bounce loop.
+   */
+  abortCurrentMovement(reason = "group override", options = {}) {
     if (this.abortController && !this.abortController.signal.aborted) {
       this.logger.warn(`Aborting movement: ${reason}`);
+      this._returnToOperationalOnAbort = Boolean(options.returnToOperational);
+      // Only external aborts (returnToOperational=false) advance the
+      // sequence-abort token. Sequence-internal aborts (e.g. shutdown's
+      // own setpoint(0) being pre-empted by a fresher shutdown/estop)
+      // come from inside executeSequence and must not terminate their
+      // own loop.
+      if (!options.returnToOperational) {
+        this.sequenceAbortToken += 1;
+      }
       this.abortController.abort();
     }
   }

src/state/stateConfig.json

@@ -127,7 +127,7 @@
         }
       },
       "maxSpeed": {
-        "default": 10,
+        "default": 1000,
         "rules": {
           "type": "number",
           "description": "Maximum speed setting."
@@ -205,6 +205,10 @@
             {
               "value": "off",
               "description": "Machine is off."
+            },
+            {
+              "value": "maintenance",
+              "description": "Machine locked for inspection or repair; automatic control disabled."
             }
           ],
           "description": "Current state of the machine."
@@ -216,7 +220,7 @@
           "type": "object",
           "schema": {
             "idle": {
-              "default": ["starting", "off","emergencystop"],
+              "default": ["starting", "off","emergencystop","maintenance"],
               "rules":{
                 "type": "set",
                 "itemType": "string",
@@ -280,7 +284,7 @@
               }
             },
             "off": {
-              "default": ["idle","emergencystop"],
+              "default": ["idle","emergencystop","maintenance"],
               "rules":{
                 "type": "set",
                 "itemType": "string",
@@ -288,12 +292,20 @@
               }
           },
           "emergencystop": {
-            "default": ["idle","off"],
+            "default": ["idle","off","maintenance"],
             "rules":{
               "type": "set",
               "itemType": "string",
               "description": "Allowed transitions from emergency stop state."
             }
+          },
+          "maintenance":  { 
+            "default": ["maintenance","idle","off"],
+            "rules":{
+              "type": "set",
+              "itemType": "string",
+              "description": "Allowed transitions for maintenance mode"
+            }
           }
         },
         "description": "Allowed transitions between states."

src/state/stateManager.js

@@ -39,6 +39,11 @@
 class stateManager {
   constructor(config, logger) {
     this.currentState = config.state.current;
+    // Wall-clock entry timestamp into currentState. Used by
+    // getRemainingTransitionS() so callers (e.g. MGC movement planner)
+    // can compute exact remaining time for timed states without
+    // approximating from the full configured duration.
+    this.stateEnteredAt = Date.now();
     this.availableStates = config.state.available;
     this.descriptions = config.state.descriptions;
     this.logger = logger;
@@ -48,10 +53,14 @@ class stateManager {
     // Define valid transitions (can be extended dynamically if needed)
     this.validTransitions = config.state.allowedTransitions;
 
-    // NEW: Initialize runtime tracking
+    //runtime tracking
     this.runTimeHours = 0; // cumulative runtime in hours
     this.runTimeStart = null; // timestamp when active state began
 
+    //maintenance tracking
+    this.maintenanceTimeStart = null; //timestamp when active state began
+    this.maintenanceTimeHours = 0; //cumulative
+
     // Define active states (runtime counts only in these states)
     this.activeStates = config.state.activeStates;
   }
@@ -60,6 +69,17 @@ class stateManager {
     return this.currentState;
   }
 
+  // Seconds remaining in the current timed state (warmingup, coolingdown,
+  // starting, stopping, …). Returns 0 for untimed states or once the
+  // configured duration has elapsed. The MGC movement planner uses this to
+  // compute exact rendezvous time for protected (non-interruptible) states.
+  getRemainingTransitionS() {
+    const d = this.transitionTimes?.[this.currentState] || 0;
+    if (d <= 0) return 0;
+    const elapsed = (Date.now() - this.stateEnteredAt) / 1000;
+    return Math.max(0, d - elapsed);
+  }
+
   transitionTo(newState,signal) {
     return new Promise((resolve, reject) => {
       if (signal && signal.aborted) {
@@ -73,8 +93,9 @@ class stateManager {
         ); //go back early and reject promise
       }
 
-      // NEW: Handle runtime tracking based on active states
+      //Time tracking based on active states
       this.handleRuntimeTracking(newState);
+      this.handleMaintenancetimeTracking(newState);
 
       const transitionDuration = this.transitionTimes[this.currentState] || 0; // Default to 0 if no transition time
       this.logger.debug(
@@ -84,6 +105,7 @@ class stateManager {
       if (transitionDuration > 0) {
         const timeoutId = setTimeout(() => {
           this.currentState = newState;
+          this.stateEnteredAt = Date.now();
           resolve(`Transition from ${this.currentState} to ${newState} completed in ${transitionDuration}s.`);
         }, transitionDuration * 1000);
         if (signal) {
@@ -94,13 +116,14 @@ class stateManager {
         }
       } else {
         this.currentState = newState;
+        this.stateEnteredAt = Date.now();
         resolve(`Immediate transition to ${this.currentState} completed.`);
       }
     });
   }
 
   handleRuntimeTracking(newState) {
-    // NEW: Handle runtime tracking based on active states
+    //Handle runtime tracking based on active states
     const wasActive = this.activeStates.has(this.currentState);
     const willBeActive = this.activeStates.has(newState);
     if (wasActive && !willBeActive && this.runTimeStart) {
@@ -120,6 +143,28 @@ class stateManager {
     }
   }
 
+  handleMaintenancetimeTracking(newState) {
+    //is this maintenance time ?
+    const wasActive = (this.currentState == "maintenance"? true:false);
+    const willBeActive = ( newState == "maintenance" ? true:false );
+
+    if (wasActive && this.maintenanceTimeStart) {
+      // stop runtime timer and accumulate elapsed time
+      const elapsed = (Date.now() - this.maintenanceTimeStart) / 3600000; // hours
+      this.maintenanceTimeHours += elapsed;
+      this.maintenanceTimeStart = null;
+      this.logger.debug(
+        `Maintenance timer stopped; elapsed=${elapsed.toFixed(
+          3
+        )}h, total=${this.maintenanceTimeHours.toFixed(3)}h.`
+      );
+    } else if (willBeActive && !this.runTimeStart) {
+      // starting new runtime
+      this.maintenanceTimeStart = Date.now();
+      this.logger.debug("Runtime timer started.");
+    }
+  }
+
   isValidTransition(newState) {
     this.logger.debug(
       `Check 1 Transition valid ? From ${
@@ -150,7 +195,6 @@ class stateManager {
     return this.descriptions[state] || "No description available.";
   }
 
-  // NEW: Getter to retrieve current cumulative runtime (active time) in hours.
   getRunTimeHours() {
     // If currently active add the ongoing duration.
     let currentElapsed = 0;
@@ -159,6 +203,15 @@ class stateManager {
     }
     return this.runTimeHours + currentElapsed;
   }
+
+  getMaintenanceTimeHours() {
+    // If currently active add the ongoing duration.
+    let currentElapsed = 0;
+    if (this.maintenanceTimeStart) {
+      currentElapsed = (Date.now() - this.maintenanceTimeStart) / 3600000;
+    }
+    return this.maintenanceTimeHours + currentElapsed;
+  }
 }
 
 module.exports = stateManager;

src/stats/index.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * Reducer-shape stats helpers shared across the platform.
+ *
+ * These were duplicated as static helpers on `Channel` and as instance
+ * methods on the older `measurement/specificClass.js`. Consolidated here so
+ * any consumer (outlier detection, monster summaries, future analytics)
+ * can import a single canonical implementation.
+ *
+ * Stream-shape filters (low/high/band-pass, kalman, savitzky-golay) stay
+ * on Channel as static helpers — they're pipeline state, not reducers.
+ */
+
+function mean(arr) {
+    if (!arr.length) return 0;
+    return arr.reduce((a, b) => a + b, 0) / arr.length;
+}
+
+// Sample std dev (n-1 denominator). A single sample has no variance to
+// estimate, so we return 0 rather than NaN — callers (e.g. z-score) treat
+// 0 as "no spread yet" and skip rejection.
+function stdDev(arr) {
+    if (arr.length <= 1) return 0;
+    const m = mean(arr);
+    const variance = arr.reduce((s, v) => s + (v - m) ** 2, 0) / (arr.length - 1);
+    return Math.sqrt(variance);
+}
+
+function median(arr) {
+    if (!arr.length) return 0;
+    const sorted = [...arr].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 !== 0
+        ? sorted[mid]
+        : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+function mad(arr) {
+    if (!arr.length) return 0;
+    const med = median(arr);
+    return median(arr.map((v) => Math.abs(v - med)));
+}
+
+// Degenerate-range pass-through matches Channel._lerp: callers rely on it
+// for early-warmup paths where input bounds haven't separated yet.
+function lerp(value, iMin, iMax, oMin, oMax) {
+    if (iMin >= iMax) return value;
+    return oMin + ((value - iMin) * (oMax - oMin)) / (iMax - iMin);
+}
+
+module.exports = { mean, stdDev, median, mad, lerp };

test/00-barrel-contract.test.js

@@ -0,0 +1,57 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const barrel = require('../index.js');
+
+test('barrel exports expected public members', () => {
+  const expected = [
+    'predict',
+    'interpolation',
+    'configManager',
+    'assetApiConfig',
+    'outputUtils',
+    'configUtils',
+    'logger',
+    'validation',
+    'assertions',
+    'MeasurementContainer',
+    'nrmse',
+    'state',
+    'coolprop',
+    'convert',
+    'MenuManager',
+    'PIDController',
+    'CascadePIDController',
+    'createPidController',
+    'createCascadePidController',
+    'childRegistrationUtils',
+    'loadCurve',
+    'gravity',
+    'AssetResolver',
+    'FileBackend',
+    'HttpBackend',
+    'assetResolver',
+  ];
+
+  for (const key of expected) {
+    assert.ok(key in barrel, `missing export: ${key}`);
+  }
+});
+
+test('barrel types are callable where expected', () => {
+  assert.equal(typeof barrel.logger, 'function');
+  assert.equal(typeof barrel.validation, 'function');
+  assert.equal(typeof barrel.configUtils, 'function');
+  assert.equal(typeof barrel.outputUtils, 'function');
+  assert.equal(typeof barrel.MeasurementContainer, 'function');
+  assert.equal(typeof barrel.convert, 'function');
+  assert.equal(typeof barrel.PIDController, 'function');
+  assert.equal(typeof barrel.CascadePIDController, 'function');
+  assert.equal(typeof barrel.createPidController, 'function');
+  assert.equal(typeof barrel.createCascadePidController, 'function');
+  assert.equal(typeof barrel.gravity.getStandardGravity, 'function');
+  assert.equal(typeof barrel.AssetResolver, 'function');
+  assert.equal(typeof barrel.FileBackend, 'function');
+  assert.equal(typeof barrel.HttpBackend, 'function');
+  assert.equal(typeof barrel.assetResolver.resolve, 'function');
+});

test/assertions.test.js

@@ -0,0 +1,14 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const Assertions = require('../src/helper/assertionUtils.js');
+
+test('assertNoNaN does not throw for valid nested arrays', () => {
+  const assertions = new Assertions();
+  assert.doesNotThrow(() => assertions.assertNoNaN([1, [2, 3, [4]]]));
+});
+
+test('assertNoNaN throws when NaN exists in nested arrays', () => {
+  const assertions = new Assertions();
+  assert.throws(() => assertions.assertNoNaN([1, [2, NaN]]), /NaN detected/);
+});