docs: add CLAUDE.md with S88 classification and superproject rule reference

References the flow-layout rule set in the EVOLV superproject
(.claude/rules/node-red-flow-layout.md) so Claude Code sessions working
in this repo know the S88 level, colour, and placement lane for this node.

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

CLAUDE.md

@@ -0,0 +1,23 @@
+# settler — Claude Code context
+
+Secondary clarifier / sludge settling.
+Part of the [EVOLV](https://gitea.wbd-rd.nl/RnD/EVOLV) wastewater-automation platform.
+
+## S88 classification
+
+| Level | Colour | Placement lane |
+|---|---|---|
+| **Unit** | `#50a8d9` | L4 |
+
+## Flow layout rules
+
+When wiring this node into a multi-node demo or production flow, follow the
+placement rule set in the **EVOLV superproject**:
+
+> `.claude/rules/node-red-flow-layout.md` (in the EVOLV repo root)
+
+Key points for this node:
+- Place on lane **L4** (x-position per the lane table in the rule).
+- Stack same-level siblings vertically.
+- Parent/children sit on adjacent lanes (children one lane left, parent one lane right).
+- Wrap in a Node-RED group box coloured `#50a8d9` (Unit).

examples/README.md

@@ -0,0 +1,8 @@
+# settler Example Flows
+
+Import-ready Node-RED examples for settler.
+
+## Files
+- basic.flow.json
+- integration.flow.json
+- edge.flow.json

examples/basic.flow.json

@@ -0,0 +1,6 @@
+[
+  {"id":"settler_basic_tab","type":"tab","label":"settler basic","disabled":false,"info":"settler basic example"},
+  {"id":"settler_basic_node","type":"settler","z":"settler_basic_tab","name":"settler basic","x":420,"y":180,"wires":[["settler_basic_dbg"]]},
+  {"id":"settler_basic_inj","type":"inject","z":"settler_basic_tab","name":"basic trigger","props":[{"p":"topic","vt":"str"},{"p":"payload","vt":"str"}],"topic":"ping","payload":"1","payloadType":"str","x":160,"y":180,"wires":[["settler_basic_node"]]},
+  {"id":"settler_basic_dbg","type":"debug","z":"settler_basic_tab","name":"settler basic debug","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":660,"y":180,"wires":[]}
+]

examples/edge.flow.json

@@ -0,0 +1,6 @@
+[
+  {"id":"settler_edge_tab","type":"tab","label":"settler edge","disabled":false,"info":"settler edge example"},
+  {"id":"settler_edge_node","type":"settler","z":"settler_edge_tab","name":"settler edge","x":420,"y":180,"wires":[["settler_edge_dbg"]]},
+  {"id":"settler_edge_inj","type":"inject","z":"settler_edge_tab","name":"unknown topic","props":[{"p":"topic","vt":"str"},{"p":"payload","vt":"str"}],"topic":"doesNotExist","payload":"x","payloadType":"str","x":170,"y":180,"wires":[["settler_edge_node"]]},
+  {"id":"settler_edge_dbg","type":"debug","z":"settler_edge_tab","name":"settler edge debug","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":660,"y":180,"wires":[]}
+]

examples/integration.flow.json

@@ -0,0 +1,6 @@
+[
+  {"id":"settler_int_tab","type":"tab","label":"settler integration","disabled":false,"info":"settler integration example"},
+  {"id":"settler_int_node","type":"settler","z":"settler_int_tab","name":"settler integration","x":420,"y":180,"wires":[["settler_int_dbg"]]},
+  {"id":"settler_int_inj","type":"inject","z":"settler_int_tab","name":"registerChild","props":[{"p":"topic","vt":"str"},{"p":"payload","vt":"str"}],"topic":"registerChild","payload":"example-child-id","payloadType":"str","x":170,"y":180,"wires":[["settler_int_node"]]},
+  {"id":"settler_int_dbg","type":"debug","z":"settler_int_tab","name":"settler integration debug","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","x":680,"y":180,"wires":[]}
+]

package.json

@@ -16,7 +16,7 @@
   "author": "P.R. van der Wilt",
   "main": "settler.js",
   "scripts": {
-    "test": "node settler.js"
+    "test": "node --test test/basic/*.test.js test/integration/*.test.js test/edge/*.test.js"
   },
   "node-red": {
     "nodes": {

settler.html

@@ -6,6 +6,8 @@
     color: "#e4a363",
     defaults: {
       name: { value: "" },
+      processOutputFormat: { value: "process" },
+      dbaseOutputFormat: { value: "influxdb" },
 
       enableLog: { value: false },
       logLevel: { value: "error" },
@@ -55,6 +57,24 @@
     <input type="text" id="node-input-name" placeholder="Name">
   </div>
 
+  <h3>Output Formats</h3>
+  <div class="form-row">
+    <label for="node-input-processOutputFormat"><i class="fa fa-random"></i> Process Output</label>
+    <select id="node-input-processOutputFormat" style="width:60%;">
+      <option value="process">process</option>
+      <option value="json">json</option>
+      <option value="csv">csv</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-dbaseOutputFormat"><i class="fa fa-database"></i> Database Output</label>
+    <select id="node-input-dbaseOutputFormat" style="width:60%;">
+      <option value="influxdb">influxdb</option>
+      <option value="json">json</option>
+      <option value="csv">csv</option>
+    </select>
+  </div>
+
   <!-- Logger fields injected here -->
   <div id="logger-fields-placeholder"></div>
 

src/nodeClass.js

@@ -31,20 +31,26 @@ class nodeClass {
    */
   _attachInputHandler() {
     this.node.on('input', (msg, send, done) => {
-
+      try {
         switch (msg.topic) {
           case 'registerChild': {
-          // Register this node as a parent of the child node
             const childId = msg.payload;
             const childObj = this.RED.nodes.getNode(childId);
+            if (!childObj || !childObj.source) {
+              this.source?.logger?.warn(`registerChild skipped: missing child/source for id=${childId}`);
+              break;
+            }
             this.source.childRegistrationUtils.registerChild(childObj.source, msg.positionVsParent);
             break;
           }
           default:
-          console.log("Unknown topic: " + msg.topic);
+            this.source?.logger?.warn(`Unknown topic: ${msg.topic}`);
+        }
+      } catch (error) {
+        this.source?.logger?.error(`Input handler failure: ${error.message}`);
       }
 
-      if (done) {
+      if (typeof done === 'function') {
         done();
       }
     });
@@ -95,7 +101,7 @@ class nodeClass {
   _attachCloseHandler() {
     this.node.on('close', (done) => {
       clearInterval(this._tickInterval);
-      done();
+      if (typeof done === 'function') done();
     });
   }
 }

src/specificClass.js

@@ -1,6 +1,18 @@
 const { childRegistrationUtils, logger, MeasurementContainer, POSITIONS } = require('generalFunctions');
 const EventEmitter = require('events');
 
+// Compatibility-safe array clone for Node runtimes without global structuredClone.
+function cloneArray(values) {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(values);
+  }
+  return Array.isArray(values) ? [...values] : values;
+}
+
+/**
+ * Settler domain model.
+ * Splits influent into effluent, sludge and return sludge based on solids balance.
+ */
 class Settler {
   constructor(config) {
     this.config = config;
@@ -31,7 +43,7 @@ class Settler {
     const F_so = F_s - F_sr;
 
     // effluent
-    const Cs_eff = structuredClone(this.Cs_in);
+    const Cs_eff = cloneArray(this.Cs_in);
     if (F_s > 0) {
       Cs_eff[7]  = 0;
       Cs_eff[8]  = 0;
@@ -42,7 +54,7 @@ class Settler {
     }
 
     // sludge
-    const Cs_s = structuredClone(this.Cs_in);
+    const Cs_s = cloneArray(this.Cs_in);
     if (F_s > 0) {
       Cs_s[7]  = this.F_in * this.Cs_in[7] / F_s;
       Cs_s[8]  = this.F_in * this.Cs_in[8] / F_s;
@@ -113,7 +125,8 @@ class Settler {
 
     reactorChild.emitter.on("stateChange", (_eventData) => {
       this.logger.debug(`State change of upstream reactor detected.`);
-      const effluent = this.upstreamReactor.getEffluent[0];
+      const raw = this.upstreamReactor.getEffluent;
+      const effluent = Array.isArray(raw) ? raw[0] : raw;
       this.F_in = effluent.payload.F;
       this.Cs_in = effluent.payload.C;
     });

test/README.md

@@ -0,0 +1,12 @@
+# settler Test Suite Layout
+
+Required EVOLV layout:
+- basic/
+- integration/
+- edge/
+- helpers/
+
+Baseline structure tests:
+- basic/structure-module-load.basic.test.js
+- integration/structure-examples.integration.test.js
+- edge/structure-examples-node-type.edge.test.js

test/basic/structure-module-load.basic.test.js

@@ -0,0 +1,8 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+test('settler module load smoke', () => {
+  assert.doesNotThrow(() => {
+    require('../../settler.js');
+  });
+});

test/edge/structure-examples-node-type.edge.test.js

@@ -0,0 +1,11 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const flow = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../examples/basic.flow.json'), 'utf8'));
+
+test('basic example includes node type settler', () => {
+  const count = flow.filter((n) => n && n.type === 'settler').length;
+  assert.equal(count >= 1, true);
+});

test/integration/structure-examples.integration.test.js

@@ -0,0 +1,23 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const dir = path.resolve(__dirname, '../../examples');
+
+function loadJson(file) {
+  return JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+}
+
+test('examples package exists for settler', () => {
+  for (const file of ['README.md', 'basic.flow.json', 'integration.flow.json', 'edge.flow.json']) {
+    assert.equal(fs.existsSync(path.join(dir, file)), true, file + ' missing');
+  }
+});
+
+test('example flows are parseable arrays for settler', () => {
+  for (const file of ['basic.flow.json', 'integration.flow.json', 'edge.flow.json']) {
+    const parsed = loadJson(file);
+    assert.equal(Array.isArray(parsed), true);
+  }
+});

test/specificClass.test.js

@@ -0,0 +1,263 @@
+/**
+ * Tests for settler specificClass (domain logic).
+ *
+ * The Settler class is a simple mass-balance separator:
+ *  - Splits influent into effluent (clarified), surplus sludge, and return sludge
+ *  - Concentrates particulate species (indices 7-12) into sludge stream
+ *  - Removes particulates from effluent stream
+ *  - registerChild: connects measurements, upstream reactors, machines
+ */
+
+const { Settler } = require('../src/specificClass');
+
+// --------------- helpers ---------------
+
+const NUM_SPECIES = 13;
+
+function makeConfig(overrides = {}) {
+  return {
+    general: {
+      name: 'TestSettler',
+      id: 'settler-test-1',
+      logging: { enabled: false, logLevel: 'error' },
+    },
+    functionality: {
+      softwareType: 'settler',
+      role: 'separator',
+      positionVsParent: 'downstream',
+    },
+    ...overrides,
+  };
+}
+
+// --------------- tests ---------------
+
+describe('Settler specificClass', () => {
+
+  describe('constructor / initialization', () => {
+    it('should create an instance with default values', () => {
+      const s = new Settler(makeConfig());
+      expect(s).toBeDefined();
+      expect(s.F_in).toBe(0);
+      expect(s.Cs_in).toEqual(new Array(NUM_SPECIES).fill(0));
+      expect(s.C_TS).toBe(2500);
+    });
+
+    it('should have null upstreamReactor and returnPump initially', () => {
+      const s = new Settler(makeConfig());
+      expect(s.upstreamReactor).toBeNull();
+      expect(s.returnPump).toBeNull();
+    });
+
+    it('should initialize an EventEmitter', () => {
+      const s = new Settler(makeConfig());
+      expect(s.emitter).toBeDefined();
+      expect(typeof s.emitter.on).toBe('function');
+    });
+
+    it('should initialize a MeasurementContainer', () => {
+      const s = new Settler(makeConfig());
+      expect(s.measurements).toBeDefined();
+    });
+  });
+
+  describe('getEffluent', () => {
+
+    describe('with zero inflow', () => {
+      it('should return three streams with zero flows', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 0;
+        s.Cs_in = new Array(NUM_SPECIES).fill(0);
+        const result = s.getEffluent;
+        expect(result).toHaveLength(3);
+        expect(result[0].payload.F).toBe(0); // effluent
+        expect(result[1].payload.F).toBe(0); // surplus sludge
+        expect(result[2].payload.F).toBe(0); // return sludge
+      });
+    });
+
+    describe('with normal inflow and particulates', () => {
+      let s;
+      let result;
+
+      beforeAll(() => {
+        s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 5000;
+        // Set concentrations: solubles at indices 0-6, particulates at 7-12
+        const C = new Array(NUM_SPECIES).fill(10);
+        C[12] = 5000; // X_TS
+        s.Cs_in = C;
+        result = s.getEffluent;
+      });
+
+      it('should return 3 output streams', () => {
+        expect(result).toHaveLength(3);
+      });
+
+      it('should have effluent topic "Fluent"', () => {
+        expect(result[0].topic).toBe('Fluent');
+      });
+
+      it('should calculate sludge flow F_s = min(F_in * X_TS_in / C_TS, F_in)', () => {
+        // F_s = min(100 * 5000 / 5000, 100) = min(100, 100) = 100
+        const F_eff = result[0].payload.F;
+        const F_so = result[1].payload.F;
+        const F_sr = result[2].payload.F;
+        // Total out should equal F_in (mass balance)
+        expect(F_eff + F_so + F_sr).toBeCloseTo(100, 5);
+      });
+
+      it('should set effluent particulate indices to zero when F_s > 0', () => {
+        const Cs_eff = result[0].payload.C;
+        for (let i = 7; i <= 12; i++) {
+          expect(Cs_eff[i]).toBe(0);
+        }
+      });
+
+      it('should keep effluent soluble indices unchanged', () => {
+        const Cs_eff = result[0].payload.C;
+        for (let i = 0; i < 7; i++) {
+          expect(Cs_eff[i]).toBe(10);
+        }
+      });
+
+      it('should concentrate particulates in sludge stream', () => {
+        const Cs_s = result[1].payload.C;
+        const F_s = Math.min((s.F_in * s.Cs_in[12]) / s.C_TS, s.F_in);
+        // Cs_s[i] = F_in * Cs_in[i] / F_s for particulate indices
+        for (let i = 7; i <= 12; i++) {
+          const expected = s.F_in * s.Cs_in[i] / F_s;
+          expect(Cs_s[i]).toBeCloseTo(expected, 5);
+        }
+      });
+    });
+
+    describe('with low X_TS and high C_TS (dilute sludge)', () => {
+      it('should produce mostly effluent flow', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 10000; // high target concentration
+        const C = new Array(NUM_SPECIES).fill(10);
+        C[12] = 100; // low X_TS in
+        s.Cs_in = C;
+        const result = s.getEffluent;
+        // F_s = min(100 * 100 / 10000, 100) = min(1, 100) = 1
+        expect(result[0].payload.F).toBeCloseTo(99, 5); // most flow is effluent
+      });
+    });
+
+    describe('mass balance', () => {
+      it('should conserve total flow (F_eff + F_so + F_sr = F_in)', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 200;
+        s.C_TS = 3000;
+        const C = new Array(NUM_SPECIES).fill(5);
+        C[12] = 2000;
+        s.Cs_in = C;
+        const result = s.getEffluent;
+        const totalOut = result[0].payload.F + result[1].payload.F + result[2].payload.F;
+        expect(totalOut).toBeCloseTo(200, 5);
+      });
+
+      it('should not produce negative flows', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 50;
+        s.C_TS = 1000;
+        const C = new Array(NUM_SPECIES).fill(0);
+        C[12] = 500;
+        s.Cs_in = C;
+        const result = s.getEffluent;
+        result.forEach(stream => {
+          expect(stream.payload.F).toBeGreaterThanOrEqual(0);
+        });
+      });
+    });
+
+    describe('no return pump', () => {
+      it('should have F_sr = 0 when there is no return pump', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 5000;
+        s.Cs_in = new Array(NUM_SPECIES).fill(10);
+        s.Cs_in[12] = 3000;
+        const result = s.getEffluent;
+        expect(result[2].payload.F).toBe(0);
+      });
+    });
+
+    describe('edge case: X_TS > C_TS (F_s clamped to F_in)', () => {
+      it('should clamp F_s to F_in when X_TS/C_TS ratio exceeds 1', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 1000;
+        s.Cs_in = new Array(NUM_SPECIES).fill(10);
+        s.Cs_in[12] = 5000; // X_TS_in > C_TS => F_s = min(500, 100) = 100
+        const result = s.getEffluent;
+        expect(result[0].payload.F).toBe(0); // all flow goes to sludge
+      });
+    });
+  });
+
+  describe('registerChild()', () => {
+    it('should not throw for null child', () => {
+      const s = new Settler(makeConfig());
+      // null child should trigger the error log but not crash
+      expect(() => s.registerChild(null, 'measurement')).not.toThrow();
+    });
+
+    it('should not throw for unknown software type with valid child', () => {
+      const s = new Settler(makeConfig());
+      const fakeChild = {
+        config: {
+          general: { name: 'fake', id: 'fake-1' },
+          functionality: { positionVsParent: 'upstream' },
+          asset: { type: 'pressure' },
+        },
+        measurements: { emitter: { on: jest.fn() } },
+      };
+      expect(() => s.registerChild(fakeChild, 'unknownType')).not.toThrow();
+    });
+  });
+
+  describe('_connectMachine()', () => {
+    it('should set returnPump for downstream machine', () => {
+      const s = new Settler(makeConfig());
+      const fakeMachine = {
+        config: {
+          general: { name: 'pump', id: 'pump-1' },
+          functionality: { positionVsParent: 'downstream' },
+        },
+      };
+      s._connectMachine(fakeMachine);
+      expect(s.returnPump).toBe(fakeMachine);
+      expect(fakeMachine.upstreamSource).toBe(s);
+    });
+
+    it('should not set returnPump for non-downstream machine', () => {
+      const s = new Settler(makeConfig());
+      const fakeMachine = {
+        config: {
+          general: { name: 'pump', id: 'pump-2' },
+          functionality: { positionVsParent: 'upstream' },
+        },
+      };
+      s._connectMachine(fakeMachine);
+      expect(s.returnPump).toBeNull();
+    });
+  });
+
+  describe('_updateMeasurement()', () => {
+    it('should update C_TS when measurement type is "quantity (tss)"', () => {
+      const s = new Settler(makeConfig());
+      s._updateMeasurement('quantity (tss)', 7000, 'atEquipment', {});
+      expect(s.C_TS).toBe(7000);
+    });
+
+    it('should not change C_TS for unrecognized measurement type', () => {
+      const s = new Settler(makeConfig());
+      s._updateMeasurement('temperature', 25, 'atEquipment', {});
+      expect(s.C_TS).toBe(2500); // unchanged
+    });
+  });
+});