@yarkivaev/scada 2.3.115 → 2.3.116

package/README.md

@@ -269,6 +269,30 @@ Opaque operation `kind` strings and generic ports (`latestForMachine`, list/upse
 | Export ports `Query` / `Stream` / `Sink` / `Job` | Export jobs + destination adapters |
 | ClickHouse + PG adapters | Plant wiring (`sokolPlant` / `edgePlant`) |
 
+### Stream transport ownership
+
+`@yarkivaev/source-to-sink` owns reusable Node.js sources, sinks and transport
+lifecycle: serial input, Modbus polling,
+MQTT/STOMP messaging, AMQP consumption and confirmed publishing, and serialized
+periodic ticks. SCADA composes these primitives with generic codecs, domain ports
+and persistence adapters. Plant packages supply source mappings, payload formats,
+queries, routing and plant-specific behavior.
+
+The SCADA AMQP telemetry, MQTT relay and operation-sync pipelines use
+`amqpSource`. It acknowledges after collector acceptance, requeues failures by
+default, and avoids settling explicitly acknowledged or rejected deliveries twice.
+Shutdown cancels consumption, drains accepted work and settlements, then closes
+the channel and connection. Reconnect and restart wait for that drain.
+`durableConsume` remains a compatibility facade over the shared AMQP session.
+Collectors that batch records acknowledge acceptance into that collector; this is
+not a guarantee that a later batch has already reached persistent storage.
+
+`intervalSource` schedules operator-cache synchronization, stale-open-segment
+sweeps, silent-stream reconciliation, PostgreSQL metric streams and the shared
+ClickHouse stream hub. Polls do not overlap; metric streams await subscribers
+before advancing their cursors. HTTP keepalive timers and domain coalescing
+windows remain owned by their respective adapters and domain policies.
+
 Depend on a pinned version (`"@yarkivaev/scada": "…#v2.3.46"`), not a local path, in downstream packages.
 
 ## CI/CD
@@ -327,3 +351,47 @@ The RabbitMQ definitions builder and management reconciler are exported as
 `@yarkivaev/scada/rabbitmq/definitions` and `@yarkivaev/scada/rabbitmq/reconcile`.
 The caller supplies the vhost, connection settings and ownership policy for
 retired routes. Reconciliation retains stored queues.
+
+### Collect multiple OPC UA endpoints
+
+`@yarkivaev/scada/opcua` exports `opcuaConnections(connections, publish, options)`
+and `validateConnections(connections)`. The same entry point exports
+`opcuaSource(connections, collector, options)` for source-to-sink composition;
+the collector accepts `{ channel, value }`. SCADA owns the OPC UA runtime and
+its `node-opcua` dependency; source-to-sink contains no OPC UA implementation.
+Offline deployment planners should import
+`validateConnections` from `@yarkivaev/scada/opcua/config`; this entry point never
+loads the network library or its startup diagnostics. Each connection has a unique `url`,
+positive `publishMs` and `heartbeatMs`, and `channels` with explicit, unique
+`nodeId` values. Additional channel metadata is opaque to this library.
+
+```js
+import opcuaConnections from '@yarkivaev/scada/opcua';
+
+const collector = opcuaConnections([
+    { url: 'opc.tcp://192.0.2.10:4840', publishMs: 100, heartbeatMs: 1000,
+        channels: [{ nodeId: 'ns=1;s=temperature', topic: 'line/temperature' }] }
+], (channel, value) => publish(channel.topic, value));
+await collector.start();
+// On process shutdown:
+await collector.stop();
+```
+
+Each endpoint owns its client, session and subscription. An unavailable endpoint
+retries independently while others continue. Start schedules these workers; it
+does not wait for every server to be available. Samples are delivered only with
+Good quality, both on change and through serialized fresh heartbeat reads.
+The caller owns value conversion, routing, timestamps and destination transport.
+Options `retryMs`, `connectTimeoutMs` and `requestTimeoutMs` bound retry timing and
+network requests; `onError(error, connection)` receives connection diagnostics.
+Do not replicate a collector with the same sources to distribute load: assign
+disjoint source sets to separate instances instead.
+
+A release can replace old collectors using
+`retirements: [{ workload: 'deployment/old-reader', selector: 'app=old-reader' }]`.
+For apply/adopt, the executor validates the new manifests first, foreground-deletes
+only these explicit Deployments, and verifies that no selected old pods remain
+before applying the replacement. This trades a collection gap for no overlap.
+The caller must bind each selector to its old Deployment; no namespace-wide prune
+is performed. Render/check/diff do not delete anything. An optional process `image`
+overrides the release image, so unrelated collectors can retain their pinned runtime.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.115",
+  "version": "2.3.116",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",
@@ -15,7 +15,9 @@
     "./startTestEdgeApi": "./src/infrastructure/http/edge/startTestEdgeApi.js",
     "./package.json": "./package.json",
     "./rabbitmq/definitions": "./src/infrastructure/messaging/rabbitmq/definitions.js",
-    "./rabbitmq/reconcile": "./src/infrastructure/messaging/rabbitmq/reconcile.js"
+    "./rabbitmq/reconcile": "./src/infrastructure/messaging/rabbitmq/reconcile.js",
+    "./opcua": "./src/infrastructure/opcua/index.js",
+    "./opcua/config": "./src/infrastructure/opcua/config.js"
   },
   "bin": {
     "modbus-to-mqtt": "./src/bin/modbus-to-mqtt.js",
@@ -33,8 +35,9 @@
     "@clickhouse/client": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@yarkivaev/simple-server": "1.0.2",
-    "@yarkivaev/source-to-sink": "1.3.10",
+    "@yarkivaev/source-to-sink": "1.3.11",
     "amqplib": "^0.10.9",
+    "node-opcua": "2.179.0",
     "pg": "^8.0.0",
     "stompit": "^1.0.0",
     "zod": "^4.6.7"

package/src/application/deploy/collectorProcesses.js

@@ -23,7 +23,7 @@ function grouped(machines, describe) {
 
 /**
  * describe(row) returns a process descriptor with a name, command and optional
- * env and resources. All sources describing the same process must agree.
+ * env, resources and image. All sources describing the same process must agree.
  * project(descriptor, rows) supplies adapter-specific env and optional hostDevices.
  * A physical device may appear in many source rows but belongs to only one process.
  */
@@ -37,6 +37,7 @@ export default function collectorProcesses(machines, describe, project) {
             devices.add(device);
         });
         return { name: descriptor.name, command: descriptor.command, env: { ...descriptor.env, ...settings.env },
-            hostDevices, resources: descriptor.resources };
+            hostDevices, resources: descriptor.resources,
+            ...(descriptor.image === undefined ? {} : { image: descriptor.image }) };
     });
 }

package/src/infrastructure/deploy/executeRelease.js

@@ -1,11 +1,27 @@
 import { execFileSync } from 'node:child_process';
 
+/** Retire only explicit Deployments with a single exact app label selector. */
+function validateRetirements(plan) {
+    if (plan.retirements !== undefined && !Array.isArray(plan.retirements)) {
+        throw new Error('retirements must be an array');
+    }
+    for (const retirement of plan.retirements || []) {
+        const name = retirement?.workload?.match(/^deployment\/(?<name>[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)$/u)?.groups.name;
+        const label = retirement?.selector?.match(/^app=(?<label>[A-Za-z0-9](?:[A-Za-z0-9_.-]*[A-Za-z0-9])?)$/u)?.groups.label;
+        if (!name || name.length > 253 || name.split('.').some((part) => { return !part || part.length > 63; })
+            || !label || label.length > 63 || (plan.workloads || []).includes(retirement.workload)) {
+            throw new Error('retirement requires an exact old deployment and app label outside desired workloads');
+        }
+    }
+}
+
 /** Validates the target before helm or kubectl can fall back to a default. */
 function validate(plan, action) {
     if (!['render', 'check', 'diff', 'apply', 'adopt', 'check-adoption'].includes(action)) {
         throw new Error('action must be render, check, diff or apply (adopt/check-adoption for migration)');
     }
     const fields = action === 'render' ? ['chart', 'release', 'namespace'] : ['chart', 'release', 'namespace', 'context', 'fieldManager'];
+    validateRetirements(plan);
     fields.forEach((key) => {
         if (typeof plan[key] !== 'string' || !plan[key].trim()) { throw new Error(`release requires ${key}`); }
     });
@@ -13,9 +29,9 @@ function validate(plan, action) {
 
 /** Every Kubernetes command, including the post-rollout hook, shares this target. */
 function kubeAt(plan, execute) {
-    return (args, input) => {
+    return (args, input, capture = false) => {
         return execute('kubectl', ['--context', plan.context, '--namespace', plan.namespace, ...args],
-            { input, encoding: 'utf8', stdio: ['pipe', 'inherit', 'inherit'] });
+            { input, encoding: 'utf8', stdio: ['pipe', capture ? 'pipe' : 'inherit', 'inherit'] });
     };
 }
 
@@ -25,8 +41,31 @@ function applyWith(kube, manifests, flags, checkOnly) {
     if (!checkOnly) { kube(args, manifests); }
 }
 
+/** A missing Deployment can still have terminating pods from an interrupted attempt. */
+function retireWorkloads(plan, kube) {
+    for (const { workload, selector } of plan.retirements || []) {
+        if (kube(['get', workload, '--ignore-not-found', '-o', 'name'], undefined, true).trim()) {
+            kube(['delete', workload, '--cascade=foreground', '--wait=true', '--timeout=300s']);
+        }
+        if (kube(['get', 'pods', '-l', selector, '-o', 'name'], undefined, true).trim()) {
+            throw new Error(`retirement pods remain for ${workload} (${selector})`);
+        }
+    }
+}
+
+function preflightRetirements(plan, action, kube, manifests) {
+    if (['apply', 'adopt'].includes(action) && plan.retirements?.length) {
+        if (action === 'adopt') {
+            applyWith(kube, manifests, ['--field-manager=kubectl-client-side-apply'], true);
+        }
+        applyWith(kube, manifests, ['--server-side', `--field-manager=${plan.fieldManager}`], true);
+        retireWorkloads(plan, kube);
+    }
+}
+
 /** Adopt legacy fields, then enforce the complete manifest before waiting for rollouts. */
 function applyRelease(plan, action, kube, manifests) {
+    preflightRetirements(plan, action, kube, manifests);
     if (['adopt', 'check-adoption'].includes(action)) {
         applyWith(kube, manifests, ['--field-manager=kubectl-client-side-apply'], action === 'check-adoption');
         if (action === 'check-adoption') { return ''; }
@@ -44,7 +83,10 @@ function applyRelease(plan, action, kube, manifests) {
  * Renders a Helm release and executes the selected kubectl action synchronously.
  * Supply chart, release, namespace and values. Cluster actions additionally require
  * an explicit context and fieldManager. prerequisites and workloads are kubectl
- * resource/name references. afterReady(plan, kube) runs after a successful apply.
+ * resource/name references. Optional retirements are { workload: "deployment/name",
+ * selector: "app=label" }; callers bind these to the old declarative app. They are
+ * removed after preflight and before any writes, with no selected pods remaining.
+ * afterReady(plan, kube) runs after a successful apply.
  */
 export default function executeRelease(plan, action = 'render', execute = execFileSync) {
     validate(plan, action);

package/src/infrastructure/ingest/durableConsume.js

@@ -1,169 +1,2 @@
-import amqp from 'amqplib';
-
-function connectBroker(url) {
-    return amqp.connect(url, { heartbeat: 10 });
-}
-
-function scheduleLater(fn, pause) {
-    return setTimeout(fn, pause);
-}
-
-function clearLater(handle) {
-    clearTimeout(handle);
-}
-
-function reportFailure(error) {
-    process.stderr.write(`amqp consume failed ${error.message}\n`);
-}
-
-function nextDelay(delay) {
-    return Math.min(delay * 2, 30000);
-}
-
-function blankState() {
-    return {
-        generation: 0,
-        timer: undefined,
-        stopping: false,
-        delay: 1000,
-        session: undefined
-    };
-}
-
-function running(state) {
-    return Boolean(state.session) || (state.generation > 0 && !state.stopping);
-}
-
-function scheduleRetry(ctx, generation) {
-    if (ctx.state.stopping || generation !== ctx.state.generation) {
-        return;
-    }
-    const pause = ctx.state.delay;
-    ctx.state.delay = nextDelay(ctx.state.delay);
-    ctx.state.timer = ctx.schedule(() => {
-        ctx.state.timer = undefined;
-        return ctx.open(generation);
-    }, pause);
-}
-
-function bindClose(ctx, generation, live) {
-    let dropped = false;
-    function lose() {
-        if (dropped || ctx.state.stopping || generation !== ctx.state.generation) {
-            return;
-        }
-        dropped = true;
-        if (ctx.state.session === live) {
-            ctx.state.session = undefined;
-        }
-        scheduleRetry(ctx, generation);
-    }
-    live.connection.on('error', lose);
-    live.connection.on('close', lose);
-    live.channel.on('error', lose);
-    live.channel.on('close', lose);
-}
-
-async function accept(ctx, generation, connection) {
-    if (ctx.state.stopping || generation !== ctx.state.generation) {
-        await connection.close();
-        return null;
-    }
-    return connection.createChannel();
-}
-
-async function keep(ctx, generation, connection, channel, tag) {
-    if (ctx.state.stopping || generation !== ctx.state.generation) {
-        await channel.close();
-        await connection.close();
-        return false;
-    }
-    const live = { connection, channel, tag };
-    ctx.state.session = live;
-    ctx.state.delay = 1000;
-    bindClose(ctx, generation, live);
-    return true;
-}
-
-async function open(ctx, generation) {
-    if (ctx.state.stopping || generation !== ctx.state.generation) {
-        return;
-    }
-    try {
-        const connection = await ctx.connect(ctx.url);
-        const channel = await accept(ctx, generation, connection);
-        if (!channel) {
-            return;
-        }
-        const tag = await ctx.subscribe(channel);
-        await keep(ctx, generation, connection, channel, tag);
-    } catch (error) {
-        ctx.report(error);
-        scheduleRetry(ctx, generation);
-    }
-}
-
-function begin(ctx) {
-    if (running(ctx.state)) {
-        return Promise.resolve();
-    }
-    ctx.state.stopping = false;
-    ctx.state.generation += 1;
-    ctx.state.delay = 1000;
-    return open(ctx, ctx.state.generation);
-}
-
-async function end(ctx) {
-    ctx.state.stopping = true;
-    ctx.state.generation += 1;
-    if (ctx.state.timer) {
-        ctx.clear(ctx.state.timer);
-        ctx.state.timer = undefined;
-    }
-    const live = ctx.state.session;
-    ctx.state.session = undefined;
-    if (!live) {
-        return;
-    }
-    await live.channel.cancel(live.tag);
-    await live.channel.close();
-    await live.connection.close();
-}
-
-/**
- * Keeps one AMQP consumer subscribed across broker restarts.
- *
- * @param {string} url - RabbitMQ AMQP URL
- * @param {function} subscribe - async (channel) => consumerTag
- * @param {object} [options] - connect, schedule, clear, report overrides
- * @returns {object} session with start and stop
- *
- * @example
- *   const session = durableConsume('amqp://localhost', async (channel) => {
- *       const tag = await channel.consume('scada.telemetry.ingest', () => {});
- *       return tag.consumerTag;
- *   });
- *   await session.start();
- */
-export default function durableConsume(url, subscribe, options = {}) {
-    const ctx = {
-        url,
-        subscribe,
-        connect: options.connect || connectBroker,
-        schedule: options.schedule || scheduleLater,
-        clear: options.clear || clearLater,
-        report: options.report || reportFailure,
-        state: blankState(),
-        open(generation) {
-            return open(ctx, generation);
-        }
-    };
-    return {
-        start() {
-            return begin(ctx);
-        },
-        stop() {
-            return end(ctx);
-        }
-    };
-}
+// Compatibility facade; transport lifecycle belongs to source-to-sink.
+export { amqpSession as default } from '@yarkivaev/source-to-sink';

package/src/infrastructure/ingest/modbus/silentStreams.js

@@ -1,4 +1,4 @@
-import { clock } from '@yarkivaev/source-to-sink';
+import { clock, intervalSource } from '@yarkivaev/source-to-sink';
 
 /**
  * Whether a stream is past the silence budget.
@@ -83,15 +83,12 @@ function gateState(config) {
         intervalSec: interval,
         sources,
         clk: config.clock || clock(),
-        delay: config.delay || ((fn, ms) => {
-            return setInterval(fn, ms);
-        }),
-        clear: config.clear || clearInterval,
+        delay: config.delay || setTimeout,
+        clear: config.clear || clearTimeout,
         lastSeen: new Map(),
         held: new Map(),
         live: new Set(),
         collector: undefined,
-        timer: undefined,
         running: false
     };
 }
@@ -119,6 +116,9 @@ export default function silentStreams(config) {
     function runPulse() {
         pulse(state);
     }
+    const ticker = intervalSource(state.intervalSec * 1000, { accept: runPulse }, {
+        schedule: state.delay, clear: state.clear
+    });
     return {
         seen(name, at = state.clk.millis()) {
             state.lastSeen.set(name, at);
@@ -134,16 +134,14 @@ export default function silentStreams(config) {
             };
         },
         start() {
+            if (state.running) { return; }
             state.running = true;
             runPulse();
-            state.timer = state.delay(runPulse, state.intervalSec * 1000);
+            void ticker.start();
         },
         stop() {
             state.running = false;
-            if (state.timer !== undefined) {
-                state.clear(state.timer);
-                state.timer = undefined;
-            }
+            void ticker.stop();
             for (const name of [...state.live]) {
                 stopOne(state, name);
             }

package/src/infrastructure/ingest/silentOpenWatch.js

@@ -1,3 +1,5 @@
+import { intervalSource } from '@yarkivaev/source-to-sink';
+
 /**
  * Periodic wall-clock sweep that closes stale open segments without waiting for STOMP.
  *
@@ -18,46 +20,7 @@ export default function silentOpenWatch(closer, budget, options) {
         throw new Error(`Budget must be a positive number: ${budget}`);
     }
     const intervalMs = options && options.intervalMs ? options.intervalMs : 5000;
-    const gate = { busy: false };
-    let timer;
-    let active = false;
-    function claim() {
-        const free = !gate.busy;
-        gate.busy = true;
-        return free;
-    }
-    function release() {
-        gate.busy = false;
-    }
-    async function tick() {
-        if (!claim()) {
-            return;
-        }
-        try {
-            await closer.close(budget);
-        } catch {
-            /* next tick retries */
-        }
-        release();
-    }
-    return {
-        async start() {
-            if (active) {
-                return;
-            }
-            active = true;
-            await tick();
-            timer = setInterval(() => {
-                void tick();
-            }, intervalMs);
-        },
-        stop() {
-            if (!active) {
-                return;
-            }
-            active = false;
-            clearInterval(timer);
-            timer = undefined;
-        }
-    };
+    return intervalSource(intervalMs, {
+        accept() { return closer.close(budget); }
+    }, { immediate: true });
 }

package/src/infrastructure/ingest/telemetry/amqpMetricsIngest.js

@@ -1,5 +1,4 @@
-import { batch, circuit, clock, timedBatch } from '@yarkivaev/source-to-sink';
-import durableConsume from '../durableConsume.js';
+import { amqpSource, batch, circuit, clock, timedBatch } from '@yarkivaev/source-to-sink';
 import deliverToMqttRecord from './deliverToMqttRecord.js';
 import metricsCodec from '../mqtt/metricsTransformer.js';
 import streamNameFromTopic from './streamNameFromTopic.js';
@@ -20,7 +19,7 @@ export function acceptTelemetryDeliver(codec, fields, content, onSeen) {
             onSeen(name);
         }
     }
-    codec.accept({ topic: record.topic, payload: record.payload.toString() });
+    return codec.accept({ topic: record.topic, payload: record.payload.toString() });
 }
 
 /**
@@ -50,16 +49,6 @@ export function telemetryConsumer(codec, channel, onSeen) {
  * @param {object} [options] - batch and prefetch options
  * @returns {object} ingest with start and stop
  */
-function subscribeMetrics(queue, prefetch, codec, onSeen) {
-    return async (channel) => {
-        await channel.assertQueue(queue, { durable: true });
-        channel.prefetch(prefetch);
-        const onMessage = telemetryConsumer(codec, channel, onSeen);
-        const tag = await channel.consume(queue, onMessage, { noAck: false });
-        return tag.consumerTag;
-    };
-}
-
 export default function amqpMetricsIngest(amqpUrl, queue, sink, options = {}) {
     const prefetch = options.prefetch || 32;
     const size = options.size || 100;
@@ -70,11 +59,11 @@ export default function amqpMetricsIngest(amqpUrl, queue, sink, options = {}) {
     const breaker = circuit(threshold, timeout, clk);
     const collector = timedBatch(batch(sink, size, breaker), interval);
     const codec = metricsCodec(collector);
-    const session = durableConsume(
-        amqpUrl,
-        subscribeMetrics(queue, prefetch, codec, options.onSeen),
-        options
-    );
+    const session = amqpSource(amqpUrl, queue, {
+        accept(delivery) {
+            return acceptTelemetryDeliver(codec, delivery.fields, delivery.content, options.onSeen);
+        }
+    }, { ...options, prefetch });
     return {
         start() {
             return session.start();

package/src/infrastructure/ingest/telemetry/amqpMqttRelay.js

@@ -1,4 +1,4 @@
-import durableConsume from '../durableConsume.js';
+import { amqpSource } from '@yarkivaev/source-to-sink';
 import deliverToMqttRecord from './deliverToMqttRecord.js';
 
 /**
@@ -34,24 +34,14 @@ export function relayConsumer(sink, channel) {
  * @param {object} [options] - prefetch count
  * @returns {object} Relay with start and stop
  */
-function subscribeRelay(queue, prefetch, sink) {
-    return async (channel) => {
-        await channel.assertQueue(queue, { durable: true });
-        channel.prefetch(prefetch);
-        const onMessage = relayConsumer(sink, channel);
-        const tag = await channel.consume(queue, onMessage, { noAck: false });
-        return tag.consumerTag;
-    };
-}
-
 export default function amqpMqttRelay(amqpUrl, queue, sink, options = {}) {
     const prefetch = options.prefetch || 32;
     let opened = false;
-    const session = durableConsume(
-        amqpUrl,
-        subscribeRelay(queue, prefetch, sink),
-        options
-    );
+    const session = amqpSource(amqpUrl, queue, {
+        accept(delivery) {
+            return sink.write([deliverToMqttRecord(delivery.fields, delivery.content)]);
+        }
+    }, { ...options, prefetch });
     return {
         start() {
             if (!opened) {
@@ -62,7 +52,8 @@ export default function amqpMqttRelay(amqpUrl, queue, sink, options = {}) {
         },
         async stop() {
             await session.stop();
-            sink.stop();
+            await sink.stop();
+            opened = false;
         }
     };
 }

package/src/infrastructure/opcua/config.js

@@ -0,0 +1,38 @@
+export function positive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive number`);
+    }
+}
+function validateChannels(channels) {
+    if (!Array.isArray(channels) || channels.length === 0) {
+        throw new TypeError('channels must be a nonempty array');
+    }
+    const nodes = new Set();
+    channels.forEach(({ nodeId }) => {
+        if (typeof nodeId !== 'string' || !nodeId.trim() || nodes.has(nodeId)) {
+            throw new TypeError('invalid or duplicate nodeId');
+        }
+        nodes.add(nodeId);
+    });
+}
+
+function validUrl(value) {
+    const url = new URL(value);
+    return url.protocol === 'opc.tcp:' && Boolean(url.hostname) && !url.username && !url.password;
+}
+export function validateConnections(connections) {
+    if (!Array.isArray(connections)) {
+        throw new TypeError('connections must be an array');
+    }
+    const urls = new Set();
+    connections.forEach((connection) => {
+        if (typeof connection.url !== 'string' || !validUrl(connection.url) || urls.has(connection.url)) {
+            throw new TypeError('invalid or duplicate OPC UA URL');
+        }
+        urls.add(connection.url);
+        positive(connection.publishMs, 'publishMs');
+        positive(connection.heartbeatMs, 'heartbeatMs');
+        validateChannels(connection.channels);
+    });
+    return connections;
+}

package/src/infrastructure/opcua/endpoint.js

@@ -0,0 +1,80 @@
+import { OPCUAClient } from 'node-opcua';
+import session from './session.js';
+
+function report(options, error, connection) {
+    try {
+        options.onError?.(error, connection);
+    } catch {
+        // Observability callbacks must not break endpoint recovery.
+    }
+}
+function delay(state, milliseconds) {
+    return new Promise((resolve) => {
+        state.wake = resolve;
+        state.timer = setTimeout(resolve, milliseconds);
+    }).finally(() => { clearTimeout(state.timer); });
+}
+function clientFor(options) {
+    return OPCUAClient.create({ endpointMustExist: false, keepSessionAlive: false,
+        connectionStrategy: { maxRetry: 0 }, transportTimeout: options.connectTimeoutMs,
+        defaultTransactionTimeout: options.requestTimeoutMs, requestedSessionTimeout: options.requestTimeoutMs * 2 });
+}
+function disconnection(client) {
+    let pending;
+    return () => {
+        pending ??= client.disconnect();
+        return pending;
+    };
+}
+async function attempt(state, connection, publish, options) {
+    const client = clientFor(options);
+    const close = disconnection(client);
+    state.close = close;
+    const current = { active: true, connection, wake: null, timer: null, pending: new Set() };
+    state.current = current;
+    try {
+        await client.connect(connection.url);
+        if (state.active) {
+            await session(current, client, connection, publish, options);
+        }
+    } catch (error) {
+        if (state.active) {
+            report(options, error, connection);
+        }
+    } finally {
+        current.active = false;
+        try { await close(); } finally { await Promise.all(current.pending); }
+    }
+}
+async function run(state, connection, publish, options) {
+    while (state.active) {
+        // Each endpoint deliberately serializes attempts and heartbeat reads.
+        // eslint-disable-next-line no-await-in-loop
+        await attempt(state, connection, publish, options);
+        if (state.active) {
+            // eslint-disable-next-line no-await-in-loop
+            await delay(state, options.retryMs);
+        }
+    }
+}
+export default function endpoint(connection, publish, options) {
+    const state = { active: false, close: null, current: null, task: null, wake: null, timer: null };
+    return {
+        start() {
+            if (!state.active) {
+                state.active = true;
+                state.task = run(state, connection, publish, options);
+            }
+        },
+        async stop() {
+            state.active = false;
+            if (state.current) {
+                state.current.active = false;
+                state.current.wake?.();
+            }
+            state.wake?.();
+            await state.close?.();
+            await state.task;
+        }
+    };
+}

package/src/infrastructure/opcua/index.js

@@ -0,0 +1,10 @@
+import opcuaSource from './source.js';
+export { validateConnections } from './config.js';
+
+/** Compatibility adapter for callback-based SCADA consumers. */
+export default function opcuaConnections(connections, publish, options = {}) {
+    if (typeof publish !== 'function') { throw new TypeError('publish must be a function'); }
+    return opcuaSource(connections, { accept: ({ channel, value }) => { return publish(channel, value); } }, options);
+}
+
+export { default as opcuaSource } from './source.js';

package/src/infrastructure/opcua/session.js

@@ -0,0 +1,60 @@
+import { checkSubscription, watchSubscription } from './subscriptionHealth.js';
+import { AttributeIds, TimestampsToReturn } from 'node-opcua';
+
+function deliver(state, channel, value, publish, options) {
+    if (state.active && !state.failure && value.statusCode.isGood()) {
+        const accepted = Promise.resolve().then(() => {
+            if (state.active && !state.failure) {
+                return publish(channel, value.value.value);
+            }
+            return undefined;
+        }).catch((error) => {
+            try {
+                options.onError?.(error, state.connection);
+            } catch {
+                // Callback isolation.
+            }
+        }).finally(() => { state.pending.delete(accepted); });
+        state.pending.add(accepted);
+    }
+}
+async function monitors(subscription, state, connection, publish, options) {
+    await Promise.all(connection.channels.map(async (channel) => {
+        const item = await subscription.monitor({ nodeId: channel.nodeId, attributeId: AttributeIds.Value },
+            { samplingInterval: connection.publishMs, discardOldest: true, queueSize: 10 }, TimestampsToReturn.Both);
+        if (!item.statusCode.isGood()) {
+            throw new Error(`Cannot monitor ${channel.nodeId}: ${item.statusCode.toString()}`);
+        }
+        item.on('changed', (value) => { deliver(state, channel, value, publish, options); });
+    }));
+}
+function pause(state, milliseconds) {
+    return new Promise((resolve) => {
+        state.wake = resolve;
+        state.timer = setTimeout(resolve, milliseconds);
+    }).finally(() => { clearTimeout(state.timer); });
+}
+async function heartbeat(state, activeSession, connection, publish, options) {
+    while (state.active) {
+        checkSubscription(state, options);
+        // Fresh reads are serialized; a slow read cannot overlap the next heartbeat.
+        // eslint-disable-next-line no-await-in-loop
+        await pause(state, connection.heartbeatMs);
+        if (state.active) {
+            checkSubscription(state, options);
+            // eslint-disable-next-line no-await-in-loop
+            const values = await activeSession.read(connection.channels.map(({ nodeId }) => { return { nodeId, attributeId: AttributeIds.Value }; }), 0);
+            values.forEach((value, index) => { deliver(state, connection.channels[index], value, publish, options); });
+        }
+    }
+}
+export default async function session(state, client, connection, publish, options) {
+    const activeSession = await client.createSession();
+    if (state.active) {
+        const subscription = await activeSession.createSubscription2({ requestedPublishingInterval: connection.publishMs,
+            requestedLifetimeCount: 30, requestedMaxKeepAliveCount: 3, maxNotificationsPerPublish: 0, publishingEnabled: true, priority: 0 });
+        watchSubscription(state, subscription);
+        await monitors(subscription, state, connection, publish, options);
+        await heartbeat(state, activeSession, connection, publish, options);
+    }
+}

package/src/infrastructure/opcua/source.js

@@ -0,0 +1,35 @@
+import { positive, validateConnections } from './config.js';
+export { validateConnections } from './config.js';
+
+/** Independent OPC UA endpoints delivering opaque channel metadata and values. */
+export default function opcuaSource(connections, collector, options = {}) {
+    const settings = { retryMs: 1000, connectTimeoutMs: 5000, requestTimeoutMs: 5000, ...options };
+    validateConnections(connections);
+    if (!collector || typeof collector.accept !== 'function') {
+        throw new TypeError('Collector must have an accept() method');
+    }
+    ['retryMs', 'connectTimeoutMs', 'requestTimeoutMs'].forEach((name) => { positive(settings[name], name); });
+    let endpoints;
+    let stopping = Promise.resolve();
+    let revision = 0;
+    return {
+        async start() {
+            revision += 1;
+            const requested = revision;
+            await stopping;
+            // Importing the package or validating a factory never loads node-opcua.
+            const { default: endpoint } = await import('./endpoint.js');
+            if (requested === revision) {
+                endpoints ??= connections.map((connection) => {
+                    return endpoint(connection, (channel, value) => { return collector.accept({ channel, value }); }, settings);
+                });
+                endpoints.forEach((item) => { item.start(); });
+            }
+        },
+        stop() {
+            revision += 1;
+            stopping = Promise.all((endpoints ?? []).map((item) => { return item.stop(); }));
+            return stopping;
+        }
+    };
+}

package/src/infrastructure/opcua/subscriptionHealth.js

@@ -0,0 +1,28 @@
+function failed(state, message) {
+    if (state.active) {
+        state.failure = new Error(message);
+        state.wake?.();
+    }
+}
+export function watchSubscription(state, subscription) {
+    state.lastPublish = Date.now();
+    state.subscription = subscription;
+    subscription.on('keepalive', () => { state.lastPublish = Date.now(); });
+    subscription.on('received_notifications', () => { state.lastPublish = Date.now(); });
+    subscription.on('terminated', () => { failed(state, 'OPC UA subscription terminated'); });
+    subscription.on('status_changed', (status) => {
+        if (!status.isGood()) {
+            failed(state, `OPC UA subscription status: ${status.toString()}`);
+        }
+    });
+}
+export function checkSubscription(state, options) {
+    const { subscription } = state;
+    const silence = Math.max(subscription.publishingInterval * subscription.maxKeepAliveCount * 3, options.requestTimeoutMs);
+    if (Date.now() - state.lastPublish > silence) {
+        failed(state, 'OPC UA subscription stopped publishing');
+    }
+    if (state.failure) {
+        throw state.failure;
+    }
+}

package/src/infrastructure/operators/operatorsSync.js

@@ -1,3 +1,5 @@
+import { intervalSource } from '@yarkivaev/source-to-sink';
+
 const DEFAULT_INTERVAL_MS = 30000;
 
 async function refresh(source, provider) {
@@ -25,33 +27,7 @@ async function refresh(source, provider) {
  */
 export default function operatorsSync(source, provider, options) {
     const intervalMs = options && options.intervalMs ? options.intervalMs : DEFAULT_INTERVAL_MS;
-    let timer;
-    let active = false;
-    async function tick() {
-        try {
-            await refresh(source, provider);
-        } catch {
-            /* next tick retries; stale snapshot remains */
-        }
-    }
-    return {
-        async start() {
-            if (active) {
-                return;
-            }
-            active = true;
-            await tick();
-            timer = setInterval(() => {
-                void tick();
-            }, intervalMs);
-        },
-        stop() {
-            if (!active) {
-                return;
-            }
-            active = false;
-            clearInterval(timer);
-            timer = undefined;
-        }
-    };
+    return intervalSource(intervalMs, {
+        accept() { return refresh(source, provider); }
+    }, { immediate: true });
 }

package/src/infrastructure/persistence/clickhouse/streamHub.js

@@ -9,14 +9,16 @@
  *   const sub = hub.watch('m1/V', since, 1000, onRow, { unit: 'V', clock });
  *   sub.cancel();
  */
+import { intervalSource } from '@yarkivaev/source-to-sink';
 import pollTopicCursors from './pollTopicCursors.js';
 
 const hubs = new WeakMap();
 
 function defaultSchedule(step, fn) {
-    const timer = setInterval(fn, step);
+    const source = intervalSource(step, { accept: fn });
+    void source.start();
     return () => {
-        clearInterval(timer);
+        return source.stop();
     };
 }
 
@@ -74,21 +76,25 @@ function cursorsOf(bucket) {
     return cursors;
 }
 
+function advance(watcher, timestamp) {
+    if (timestamp.getTime() > watcher.lastTs.getTime()) {
+        watcher.lastTs = timestamp;
+    }
+}
+
 function dispatch(bucket, rows) {
-    rows.forEach((row) => {
+    return rows.reduce(async (previous, row) => {
+        await previous;
         const group = bucket.watchers.get(row.topic);
-        if (!group) {
-            return;
-        }
+        if (!group) { return; }
         const timestamp = parseTimestamp(row.ts);
-        group.forEach((watcher) => {
-            if (timestamp.getTime() <= watcher.lastTs.getTime()) {
-                return;
-            }
-            watcher.callback({ timestamp, value: row.value, unit: watcher.unit });
-            watcher.lastTs = timestamp;
-        });
-    });
+        await [...group].reduce(async (previousWatcher, watcher) => {
+            await previousWatcher;
+            if (timestamp.getTime() <= watcher.lastTs.getTime()) { return; }
+            await watcher.callback({ timestamp, value: row.value, unit: watcher.unit });
+            advance(watcher, timestamp);
+        }, Promise.resolve());
+    }, Promise.resolve());
 }
 
 function buildHub(connection, schedule) {
@@ -106,7 +112,7 @@ function buildHub(connection, schedule) {
                     cursorsOf(bucket),
                     bucket.clock()
                 );
-                dispatch(bucket, rows);
+                await dispatch(bucket, rows);
             } catch (err) {
                 console.error( // eslint-disable-line no-console
                     `Stream batch failed on ${connection.url()}:`,

package/src/infrastructure/persistence/metricsSensor.js

@@ -1,3 +1,4 @@
+import { intervalSource } from '@yarkivaev/source-to-sink';
 import seriesRows, { parseTimestamp } from './seriesRows.js';
 
 function pollStream(spec) {
@@ -6,21 +7,23 @@ function pollStream(spec) {
         return new Date();
     });
     let lastTs = since;
-    const timer = setInterval(async () => {
+    const source = intervalSource(step, { async accept() {
         try {
             const rows = await read.poll(topic, lastTs.toISOString(), time().toISOString());
-            rows.forEach((row) => {
+            await rows.reduce(async (previous, row) => {
+                await previous;
                 const timestamp = parseTimestamp(row.ts);
-                callback({ timestamp, value: row.value, unit });
+                await callback({ timestamp, value: row.value, unit });
                 lastTs = timestamp;
-            });
+            }, Promise.resolve());
         } catch {
             /* next poll retries */
         }
-    }, step);
+    } });
+    void source.start();
     return {
         cancel() {
-            clearInterval(timer);
+            return source.stop();
         }
     };
 }

package/src/infrastructure/sync/operationSyncIngest.js

@@ -1,4 +1,4 @@
-import durableConsume from '../ingest/durableConsume.js';
+import { amqpSource } from '@yarkivaev/source-to-sink';
 import operationCodec from './operationCodec.js';
 import operationSyncSink from './operationSyncSink.js';
 
@@ -43,25 +43,13 @@ export function operationConsumer(codec, channel) {
  *   const ingest = operationSyncIngest(amqpUrl, 'scada.operations.ingest', dataAccess.operations);
  *   await ingest.start();
  */
-function subscribeOperations(queue, prefetch, codec) {
-    return async (channel) => {
-        await channel.assertQueue(queue, { durable: true });
-        channel.prefetch(prefetch);
-        const onMessage = operationConsumer(codec, channel);
-        const tag = await channel.consume(queue, onMessage, { noAck: false });
-        return tag.consumerTag;
-    };
-}
-
 export default function operationSyncIngest(amqpUrl, queue, operations, options = {}) {
     const prefetch = options.prefetch || 32;
     const sink = operationSyncSink(operations);
     const codec = operationCodec(sink);
-    const session = durableConsume(
-        amqpUrl,
-        subscribeOperations(queue, prefetch, codec),
-        options
-    );
+    const session = amqpSource(amqpUrl, queue, {
+        accept(delivery) { return acceptOperationDeliver(codec, delivery.content); }
+    }, { ...options, prefetch });
     return {
         start() {
             return session.start();