feat(commands): adopt unified command envelope — msg.origin provenance

Resolve command origin via msg.origin (registry-stamped, default parent) with a
legacy fallback to the previous payload.source/msg.source field. Feeds the
existing mode/allowedSources arbitration unchanged.

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

src/commands/handlers.js

@@ -9,6 +9,16 @@ function _logger(source, ctx) {
   return ctx?.logger || source?.logger || null;
 }
 
+// Resolve the command origin (control authority: parent | GUI | fysical).
+// The shared commandRegistry stamps msg.origin (default 'parent'); legacy flows
+// carried it as payload.source. Prefer the legacy field when present so existing
+// flows keep working, otherwise use the registry-stamped msg.origin.
+function _origin(msg) {
+  const p = msg && msg.payload;
+  if (p && typeof p === 'object' && typeof p.source === 'string' && p.source) return p.source;
+  return (typeof msg?.origin === 'string' && msg.origin) ? msg.origin : 'parent';
+}
+
 exports.setMode = (source, msg) => {
   source.setMode(msg.payload);
 };
@@ -31,25 +41,18 @@ exports.registerChild = (source, msg, ctx) => {
 };
 
 exports.execSequence = async (source, msg) => {
-  const { source: seqSource, action: seqAction, parameter } = msg.payload || {};
-  await source.handleInput(seqSource, seqAction, parameter);
+  const { action: seqAction, parameter } = msg.payload || {};
+  await source.handleInput(_origin(msg), seqAction, parameter);
 };
 
 exports.totalFlowChange = async (source, msg) => {
   const payload = msg.payload || {};
-  if (payload && typeof payload === 'object' && Object.prototype.hasOwnProperty.call(payload, 'source')) {
-    const src = payload.source || 'parent';
   const action = payload.action || 'totalFlowChange';
-    await source.handleInput(src, action, payload);
-    return;
-  }
-  await source.handleInput('parent', 'totalFlowChange', payload);
+  await source.handleInput(_origin(msg), action, payload);
 };
 
 exports.emergencyStop = async (source, msg) => {
-  const payload = msg.payload || {};
-  const src = payload.source || 'parent';
-  await source.handleInput(src, 'emergencystop');
+  await source.handleInput(_origin(msg), 'emergencystop');
 };
 
 exports.setReconcileInterval = (source, msg) => {

src/commands/index.js

@@ -12,7 +12,7 @@ module.exports = [
     topic: 'set.mode',
     aliases: ['setMode'],
     payloadSchema: { type: 'string' },
-    description: 'Switch the valve group between auto / manual control modes.',
+    description: 'Switch the operating mode. Allowed: `auto`, `virtualControl`, `fysicalControl`, `maintenance` (schema-validated in `valveGroupControl.json` → `mode.current`).',
     handler: handlers.setMode,
   },
   {

vgc.html

@@ -14,7 +14,7 @@
 <script>
     RED.nodes.registerType('valveGroupControl',{
     category: "EVOLV",
-    color: "#50a8d9",
+    color: "#2A8A82",
     defaults: {
       // Define default properties
       name: { value: "" },
@@ -91,6 +91,7 @@
     <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="frost">frost</option>
       <option value="json">json</option>
       <option value="csv">csv</option>
     </select>

wiki/Reference-Contracts.md

@@ -15,19 +15,19 @@
 
 The registry lives in `src/commands/index.js`. Each descriptor maps a canonical `msg.topic` to its handler; aliases emit a one-time deprecation warning the first time they fire.
 
-<!-- BEGIN AUTOGEN: topic-contract — populate via wiki-gen tool (TODO) -->
+<!-- BEGIN AUTOGEN: topic-contract -->
 
 | Canonical topic | Aliases | Payload | Unit | Effect |
-|:---|:---|:---|:---|:---|
-| `set.mode` | `setMode` | `string` (`auto` / `virtualControl` / `fysicalControl` / `maintenance`) | &mdash; | Switch operational mode via `source.setMode(payload)`. Each mode has its own allow-list of sources (`mode.allowedSources`). |
-| `set.position` | `setpoint` | any | &mdash; | **No-op pending Phase 7.** Reserved for future per-valve positional override; the handler is debug-logged only. |
-| `child.register` | `registerChild` | `string` (child node id) | &mdash; | Resolve via `RED.nodes.getNode`; if the child exposes `.source`, register through `childRegistrationUtils.registerChild(child.source, msg.positionVsParent)`. |
-| `cmd.execSequence` | `execSequence` | `{ source, action, parameter }` | &mdash; | Forward to `source.handleInput(source, action, parameter)`. The `action` typically names a sequence; the parameter typically names the state list. |
-| `data.totalFlow` | `totalFlowChange` | number, `{ value, position?, variant?, unit? }`, or `{ source, action, ... }` | `volumeFlowRate` (default `m3/h`) | Update total measured/predicted flow at the configured position; drives `calcValveFlows` to re-distribute. If `payload.source` is present, route via `handleInput(src, action, payload)`; otherwise treat as `parent`/`totalFlowChange`. |
-| `cmd.emergencyStop` | `emergencyStop`, `emergencystop` | optional `{ source }` | &mdash; | Run the `emergencystop` sequence via `handleInput(src, 'emergencystop')`. Default source is `parent`. |
-| `set.reconcileInterval` | `setReconcileInterval` | number &mdash; seconds (> 0) | seconds | Re-tune the periodic flow-reconciliation interval (`setReconcileIntervalSeconds`). Min clamp 100 ms. Non-finite or &le; 0 logs a warn and is dropped. |
+|---|---|---|---|---|
+| `set.mode` | `setMode` | `string` | — | Switch the operating mode. Allowed: `auto`, `virtualControl`, `fysicalControl`, `maintenance` (schema-validated in `valveGroupControl.json` → `mode.current`). |
+| `set.position` | `setpoint` | any | — | Set the group-level valve position (currently a no-op pending Phase 7). |
+| `child.register` | `registerChild` | `string` | — | Register a child valve with this group. |
+| `cmd.execSequence` | `execSequence` | `object` | — | Run a group-wide sequence (startup / shutdown / emergencystop). |
+| `data.totalFlow` | `totalFlowChange` | any | — | Notify the group that the total flow setpoint has changed. |
+| `cmd.emergencyStop` | `emergencyStop`, `emergencystop` | any | — | Trigger an emergency stop across all valves in the group. |
+| `set.reconcileInterval` | `setReconcileInterval` | any | — | Update the reconciliation interval (seconds). |
 
-<!-- END AUTOGEN -->
+<!-- END AUTOGEN: topic-contract -->
 
 ### Mode / source allow-lists