@yarkivaev/scada 2.3.86 → 2.3.87

package/README.md

@@ -132,7 +132,7 @@ Main entry (`import { … } from '@yarkivaev/scada'`):
 | `stompTimeline`, `stompAlerts`, `userDecisions` | STOMP messaging |
 | `machineOwners`, `ownerTimeline`, `httpTimeline`, `httpOperations` | Owner-routed timeline and operations write (local or edge HTTP) |
 | `mqttMetrics`, `modbusMqtt`, `activityTracking`, `amqpMetricsIngest` | Ingest pipelines |
-| `analyticsMcp`, `namespaceTree`, `coverageSpans`, `sqlGuard` | Analytics MCP, path index, coverage spans, read-only SQL guard |
+| `analyticsMcp`, `namespaceTree`, `coverageSpans`, `coverageCursor`, `sqlGuard` | Analytics MCP, path index, coverage spans, checkpoint-or-sample cursor, read-only SQL guard |
 
 Subpath exports:
 

package/index.js

@@ -88,5 +88,6 @@ export { default as siteSyncTargets } from './src/application/sync/siteSyncTarge
 export { default as siteSyncBind } from './src/application/sync/siteSyncBind.js';
 export { default as namespaceTree } from './src/domain/namespace/namespaceTree.js';
 export { default as coverageSpans } from './src/domain/span/coverageSpans.js';
+export { default as coverageCursor } from './src/application/mcp/coverageCursor.js';
 export { default as sqlGuard } from './src/domain/sql/sqlGuard.js';
 export { default as analyticsMcp } from './src/application/mcp/analyticsMcp.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.86",
+  "version": "2.3.87",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",

package/src/application/mcp/coverageCursor.js

@@ -0,0 +1,116 @@
+const EMPTY = '1970-01-01T00:00:00.000Z';
+
+/**
+ * Reads epoch milliseconds from a cursor value.
+ *
+ * @param {Date|number|string|object} value - instant or { at }
+ * @returns {number} epoch milliseconds, or NaN
+ *
+ * @example
+ *   instant({ at: '2024-11-02T03:04:05.137Z' });
+ */
+function instant(value) {
+    if (value && typeof value === 'object' && !(value instanceof Date) && Object.hasOwn(value, 'at')) {
+        return instant(value.at);
+    }
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (value === undefined || value === null || value === '') {
+        return Number.NaN;
+    }
+    return Date.parse(String(value));
+}
+
+/**
+ * Formats a covered instant, treating epoch and gaps as empty.
+ *
+ * @param {Date|number|string|object} value - instant
+ * @returns {string} ISO instant, or the empty cursor
+ *
+ * @example
+ *   covered('2024-11-02T03:04:05.137Z');
+ */
+function covered(value) {
+    const at = instant(value);
+    if (!Number.isFinite(at) || at <= 0) {
+        return EMPTY;
+    }
+    return new Date(at).toISOString();
+}
+
+/**
+ * Latest sample instant, or the empty cursor when none exist.
+ *
+ * @param {Array} samples - instants or objects with ts
+ * @returns {string} ISO instant
+ *
+ * @example
+ *   latest([{ ts: '2024-11-02T03:04:05.137Z' }]);
+ */
+function latest(samples) {
+    const rows = Array.isArray(samples) ? samples : [];
+    let mark = 0;
+    for (const sample of rows) {
+        const raw = sample && typeof sample === 'object' && Object.hasOwn(sample, 'ts')
+            ? sample.ts
+            : sample;
+        const at = instant(raw);
+        if (Number.isFinite(at) && at > mark) {
+            mark = at;
+        }
+    }
+    return mark > 0 ? new Date(mark).toISOString() : EMPTY;
+}
+
+/**
+ * Reads the newest ingest checkpoint for a machine.
+ *
+ * @param {object|undefined} pool - pg pool
+ * @param {string} machine - machine id
+ * @returns {Promise<string>} ISO instant, or the empty cursor
+ *
+ * @example
+ *   checkpoint(pool, 'machine1');
+ */
+async function checkpoint(pool, machine) {
+    if (!pool) {
+        return EMPTY;
+    }
+    const result = await pool.query(
+        'SELECT cursor_at FROM ingest_checkpoints WHERE machine = $1 ORDER BY cursor_at DESC LIMIT 1',
+        [machine]
+    );
+    if (result.rows.length === 0) {
+        return EMPTY;
+    }
+    return covered(result.rows[0].cursor_at);
+}
+
+/**
+ * Coverage cursor: ingest checkpoint, else latest metric instant.
+ *
+ * Central ingest does not write ingest_checkpoints. When that table is empty,
+ * the latest sample is the covered bound so coverageSpans can paint present
+ * and absent instead of the whole window unknown.
+ *
+ * @param {object|undefined} pool - pg pool
+ * @param {Function} samples - async (args) => sample list
+ * @returns {Function} cursor port ({ machine, path }) => ISO instant
+ *
+ * @example
+ *   coverageCursor(pool, ({ path }) => ports.samples({ path }))({ machine: 'm1' });
+ */
+export default function coverageCursor(pool, samples) {
+    return async function bound(args) {
+        const machine = args.machine || args.path;
+        const mark = await checkpoint(pool, machine);
+        if (instant(mark) > 0) {
+            return mark;
+        }
+        return latest(await samples(args));
+    };
+}

package/src/application/metricsPlant.js

@@ -1,7 +1,25 @@
 import plant from '../domain/plant/plant.js';
 import initialized from '../domain/shared/initialized.js';
+import pgAlerts from '../infrastructure/persistence/pg/alerts.js';
 import postgresPool from '../infrastructure/persistence/postgresPool.js';
 
+/**
+ * Plant extras: injected ports, or pgAlerts when a pool exists.
+ *
+ * @param {object} options - optional operations and alerts
+ * @param {object|undefined} pool - pg pool
+ * @returns {object} plant options
+ *
+ * @example
+ *   extras({ operations }, pool);
+ */
+function extras(options, pool) {
+    return {
+        operations: options.operations,
+        alerts: options.alerts || (pool ? pgAlerts(pool) : undefined)
+    };
+}
+
 /**
  * Generic plant factory wiring sensors and a shop factory over a connection.
  *
@@ -32,5 +50,5 @@ export default async function metricsPlant(machines, options) {
         segments: options.segments,
         shopName: options.shopName
     });
-    return plant(initialized({ [shop.name()]: shop }, Object.values));
+    return plant(initialized({ [shop.name()]: shop }, Object.values), extras(options, pool));
 }

package/src/application/shopWithTimeline.js

@@ -73,6 +73,13 @@ function writePort(name, decisions, owners) {
     }, owners)(name);
 }
 
+function demandWrite(name, decisions, owners) {
+    if (!decisions) {
+        throw new Error(`Timeline write requires userDecisions for ${name}`);
+    }
+    return writePort(name, decisions, owners);
+}
+
 function ownsLocal(owners, name) {
     if (!owners) {
         return true;
@@ -153,23 +160,23 @@ async function answer(scope, requestId, body, audit) {
 }
 
 /**
- * Builds a machine timeline from PostgreSQL persistence and STOMP user decisions.
+ * Builds a machine timeline from PostgreSQL when a pool exists.
  *
- * Optional owners registry routes retag/respond to an edge HTTP plant API.
+ * Reads do not need userDecisions. retag and respond throw without it.
+ * Optional owners registry routes those writes to an edge HTTP plant API.
  *
  * @param {string} name - machine id
- * @param {object} options - pool, userDecisions, optional owners
+ * @param {object} options - pool, optional userDecisions and owners
  * @returns {object} timeline port with list, rowAt, pending, stream, retag, respond, bus
  *
  * @example
- *   const tl = shopWithTimeline('machine1', { pool, userDecisions, owners });
+ *   const tl = shopWithTimeline('machine1', { pool });
  */
 export default function shopWithTimeline(name, options) {
     const { pool, userDecisions: decisions, owners, segments } = options;
-    if (pool && decisions) {
+    if (pool) {
         const bus = pubsub();
         const read = pgTimeline(pool, name);
-        const write = writePort(name, decisions, owners);
         const port = timeline(read, bus);
         return {
             list: port.list,
@@ -179,6 +186,7 @@ export default function shopWithTimeline(name, options) {
             stream: port.stream,
             bus,
             async retag(start, tags, properties, audit) {
+                const write = demandWrite(name, decisions, owners);
                 if (ownsLocal(owners, name)) {
                     await confirm(pool, {
                         machine: name,
@@ -192,6 +200,7 @@ export default function shopWithTimeline(name, options) {
                 bus.emit({ type: 'resolved', segment: resolvedStub(start, tags, properties), audit });
             },
             respond(requestId, body, audit) {
+                const write = demandWrite(name, decisions, owners);
                 return answer({ pool, owners, name, segments, write, bus }, requestId, body, audit);
             }
         };

package/src/domain/plant/plant.js

@@ -3,7 +3,7 @@
  * Provides initialization for all contained shops.
  *
  * @param {object} shops - initialized list of shops
- * @param {object} [options] - operations, topology
+ * @param {object} [options] - operations, alerts, topology
  * @returns {object} plant with shops property and init method
  *
  * @example
@@ -14,6 +14,7 @@ export default function plant(shops, options = {}) {
     return {
         shops,
         operations: options.operations,
+        alerts: options.alerts,
         topology: options.topology,
         init() {
             shops.init();

package/src/infrastructure/persistence/pg/alerts.js

@@ -1,12 +1,41 @@
 /**
- * PostgreSQL alert hydration port for supervisor-sink and plant STOMP alerts.
+ * Builds a filtered alerts SELECT.
+ *
+ * @param {object} filters - optional machine, from, to
+ * @returns {{sql: string, prm: Array}} query
+ *
+ * @example
+ *   listSql({ machine: 'm1', from: start, to: end });
+ */
+function listSql(filters) {
+    const prm = [];
+    const clauses = [];
+    const scope = filters || {};
+    if (scope.machine) {
+        prm.push(scope.machine);
+        clauses.push(`machine = $${prm.length}`);
+    }
+    if (scope.from) {
+        prm.push(scope.from);
+        clauses.push(`"timestamp" >= $${prm.length}`);
+    }
+    if (scope.to) {
+        prm.push(scope.to);
+        clauses.push(`"timestamp" <= $${prm.length}`);
+    }
+    const where = clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`;
+    return { prm, sql: `SELECT * FROM alerts${where} ORDER BY timestamp` };
+}
+
+/**
+ * PostgreSQL alert hydration and range-read port.
  *
  * @param {object} pool - pg pool
- * @returns {object} alerts port with put and listUnacknowledged
+ * @returns {object} alerts port with put, list, and listUnacknowledged
  *
  * @example
  *   const store = alertsStatePg(pool);
- *   const rows = await store.listUnacknowledged({ machine: 'm1' });
+ *   const rows = await store.list({ machine: 'm1', from, to });
  */
 export default function alertsStatePg(pool) {
     return {
@@ -25,6 +54,11 @@ export default function alertsStatePg(pool) {
             );
             return inserted.rows[0];
         },
+        async list(filters) {
+            const query = listSql(filters);
+            const result = await pool.query(query.sql, query.prm);
+            return result.rows;
+        },
         async listUnacknowledged(filters) {
             let sql = 'SELECT * FROM alerts WHERE acknowledged = FALSE';
             const prm = [];