@yarkivaev/scada 2.3.87 → 2.3.88

package/README.md

@@ -4,13 +4,16 @@ Generic industrial monitoring domain, state persistence, and HTTP APIs (`@yarkiv
 
 This package is plant-agnostic: it defines `plant` → `shop` → `machine` hierarchy, timeline and alerts, sensor read ports, STOMP ingest pipelines, and PostgreSQL/ClickHouse adapters. Plant-specific routes, sensors, HMI strings, and tag taxonomies live in downstream plant packages.
 
-`analyticsMcp` is a stateless Streamable HTTP MCP server. The plant package supplies a `namespaceTree` (path, kind, silence, source topic) and read ports. Tools address nodes by path. `query_postgres` is registered only when a standby query port is supplied. Each call writes one JSON line to the injected journal. `GET /metrics` exposes call counts and in-flight reads.
+`analyticsMcp` is a stateless Streamable HTTP MCP server. The plant package supplies a `namespaceTree` (path, kind, silence, source topic), read ports, and the tag catalog already used by `plantApi({ tagCatalog })`. Tools address nodes by path. `query_postgres` is registered only when a standby query port is supplied. Each SQL engine runs one query at a time. Each call writes one JSON line to the injected journal. `GET /metrics` exposes call counts and in-flight reads.
+
+Resources: `plant://topology`, `plant://bindings`, `plant://tags`, `plant://schema/postgres`, `plant://schema/clickhouse`. Column lists live in the schema resources, not here.
 
 ```javascript
-import { analyticsMcp, namespaceTree } from '@yarkivaev/scada';
+import { analyticsMcp, namespaceTree, tagCatalog } from '@yarkivaev/scada';
 
 const mcp = analyticsMcp({
   tree: namespaceTree(nodes),
+  catalog: tagCatalog(),
   tokens: { secret: 'analyst' },
   journal(line) { process.stdout.write(line); },
   ports: {
@@ -21,7 +24,7 @@ const mcp = analyticsMcp({
 await mcp.listen(0, '127.0.0.1');
 ```
 
-`ports.queryPostgres` registers `query_postgres`. `extend(server)` may add plant tools. `POST /mcp` requires `Authorization: Bearer`.
+`ports.queryPostgres` registers `query_postgres`. `extend(server)` may add plant tools. `POST /mcp` requires `Authorization: Bearer`. Coverage spans add the overlapping timeline segment name as `phase`. The process journal is stdout only; `activityTracking` still writes Loki HTTP access into `activity.http_access`, not `activity.mcp_calls`.
 
 Repository: `https://github.com/yarkivaev/scada`
 
@@ -132,7 +135,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`, `coverageCursor`, `sqlGuard` | Analytics MCP, path index, coverage spans, checkpoint-or-sample cursor, read-only SQL guard |
+| `analyticsMcp`, `namespaceTree`, `coverageSpans`, `coverageOverlay`, `coverageCursor`, `sqlGuard` | Analytics MCP, path index, coverage spans, timeline-name overlay, checkpoint-or-sample cursor, read-only SQL guard |
 
 Subpath exports:
 

package/index.js

@@ -87,6 +87,7 @@ export { default as siteSyncSites } from './src/application/sync/siteSyncSites.j
 export { default as siteSyncTargets } from './src/application/sync/siteSyncTargets.js';
 export { default as siteSyncBind } from './src/application/sync/siteSyncBind.js';
 export { default as namespaceTree } from './src/domain/namespace/namespaceTree.js';
+export { default as coverageOverlay } from './src/domain/span/coverageOverlay.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';

package/package.json

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

package/src/application/mcp/analyticsMcp.js

@@ -2,6 +2,7 @@ import http from 'node:http';
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import mcpFlight from './mcpFlight.js';
 import mcpMetrics from './mcpMetrics.js';
 import observe from './mcpObserve.js';
 import registerCoverage from './mcpCoverage.js';
@@ -98,20 +99,25 @@ function extendServer(server, bundle) {
  * Builds one stateless server for a single HTTP request.
  *
  * @param {object} bundle - analyticsMcp bundle
- * @param {object} metrics - prometheus counters
+ * @param {object} runtime - metrics and SQL flight
  * @param {string} caller - bearer caller name
  * @returns {object} McpServer
  *
  * @example
- *   openServer(bundle, metrics, 'analyst');
+ *   openServer(bundle, runtime, 'analyst');
  */
-function openServer(bundle, metrics, caller) {
+function openServer(bundle, runtime, caller) {
     const server = new McpServer(serverInfo());
-    observe(server, { caller, journal: bundle.journal, metrics });
+    observe(server, {
+        caller,
+        flight: runtime.flight,
+        journal: bundle.journal,
+        metrics: runtime.metrics
+    });
     registerReads(server, bundle.ports, bundle.tree);
     registerCoverage(server, bundle.ports, bundle.tree);
     registerQueries(server, bundle.ports);
-    registerResources(server, bundle.tree);
+    registerResources(server, bundle.tree, bundle.catalog);
     extendServer(server, bundle);
     return server;
 }
@@ -183,8 +189,8 @@ function releaser(transport, server) {
  * @example
  *   dispatch(req, res, bundle, metrics, 'analyst');
  */
-async function dispatch(req, res, bundle, metrics, caller) {
-    const server = openServer(bundle, metrics, caller);
+async function dispatch(req, res, bundle, runtime, caller) {
+    const server = openServer(bundle, runtime, caller);
     const transport = new StreamableHTTPServerTransport({
         enableJsonResponse: true,
         sessionIdGenerator: undefined
@@ -214,13 +220,13 @@ async function dispatch(req, res, bundle, metrics, caller) {
  * @example
  *   postMcp(req, res, bundle, metrics);
  */
-async function postMcp(req, res, bundle, metrics) {
+async function postMcp(req, res, bundle, runtime) {
     const name = callerName(req, bundle.tokens);
     if (name.length === 0) {
         res.writeHead(401).end();
         return;
     }
-    await dispatch(req, res, bundle, metrics, name);
+    await dispatch(req, res, bundle, runtime, name);
 }
 
 /**
@@ -233,9 +239,9 @@ async function postMcp(req, res, bundle, metrics) {
  * @example
  *   writeMetrics(res, metrics);
  */
-function writeMetrics(res, metrics) {
+function writeMetrics(res, runtime) {
     res.writeHead(200, { 'content-type': 'text/plain; version=0.0.4; charset=utf-8' });
-    res.end(metrics.text());
+    res.end(runtime.metrics.text());
 }
 
 /**
@@ -250,13 +256,13 @@ function writeMetrics(res, metrics) {
  * @example
  *   route(req, res, bundle, metrics);
  */
-function route(req, res, bundle, metrics) {
+function route(req, res, bundle, runtime) {
     if (req.method === 'GET' && req.url === '/metrics') {
-        writeMetrics(res, metrics);
+        writeMetrics(res, runtime);
         return Promise.resolve();
     }
     if (req.method === 'POST' && req.url === '/mcp') {
-        return postMcp(req, res, bundle, metrics);
+        return postMcp(req, res, bundle, runtime);
     }
     res.writeHead(404).end();
     return Promise.resolve();
@@ -291,8 +297,8 @@ function fail(res) {
  * @example
  *   onRequest(req, res, bundle, metrics);
  */
-function onRequest(req, res, bundle, metrics) {
-    route(req, res, bundle, metrics).catch(() => {
+function onRequest(req, res, bundle, runtime) {
+    route(req, res, bundle, runtime).catch(() => {
         fail(res);
     });
 }
@@ -352,18 +358,18 @@ function shut(server) {
  * is a function. extend(server) may register more tools. POST /mcp speaks MCP.
  * GET /metrics is Prometheus text.
  *
- * @param {object} bundle - tree, tokens, journal, ports, optional extend
+ * @param {object} bundle - tree, tokens, journal, ports, optional catalog and extend
  * @returns {object} listen and close
  *
  * @example
- *   const mcp = analyticsMcp({ tree, tokens, journal, ports });
+ *   const mcp = analyticsMcp({ tree, tokens, journal, ports, catalog });
  *   await mcp.listen(0, '127.0.0.1');
  */
 export default function analyticsMcp(bundle) {
     assertBundle(bundle);
-    const metrics = mcpMetrics();
+    const runtime = { flight: mcpFlight(), metrics: mcpMetrics() };
     const server = http.createServer((req, res) => {
-        onRequest(req, res, bundle, metrics);
+        onRequest(req, res, bundle, runtime);
     });
     return Object.freeze({
         close() {

package/src/application/mcp/mcpCoverage.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import coverageOverlay from '../../domain/span/coverageOverlay.js';
 import coverageSpans from '../../domain/span/coverageSpans.js';
 import { toolText } from './mcpText.js';
 
@@ -34,13 +35,13 @@ async function coverOne(path, args, ports, tree) {
     const node = tree.resolve(path);
     const samples = await ports.samples({ from: args.from, path, to: args.to });
     const cursor = await ports.cursor({ path });
-    const spans = coverageSpans(
+    const spans = coverageOverlay(coverageSpans(
         samples,
         args.from,
         args.to,
         node.silenceSeconds * 1000,
         cursorAt(cursor)
-    );
+    ), await ports.segments({ from: args.from, path, to: args.to }));
     return {
         path,
         spans: spans.slice(0, 200),

package/src/application/mcp/mcpFlight.js

@@ -0,0 +1,42 @@
+/**
+ * One in-flight callback per SQL engine.
+ *
+ * ClickHouse and Postgres each keep a tail promise. A later job waits for
+ * that tail before it runs, so two query tools never execute together.
+ *
+ * @returns {object} run(engine, job)
+ *
+ * @example
+ *   const flight = mcpFlight();
+ *   await flight.run('clickhouse', () => query('SELECT 1'));
+ */
+export default function mcpFlight() {
+    const tail = {
+        clickhouse: Promise.resolve(),
+        postgres: Promise.resolve()
+    };
+    return Object.freeze({
+        /**
+         * Runs job after the previous job for this engine settles.
+         *
+         * @param {string} engine - clickhouse or postgres
+         * @param {Function} job - callback
+         * @returns {Promise<*>} job result
+         */
+        run(engine, job) {
+            const prior = tail[engine];
+            let release;
+            const held = new Promise((resolve) => {
+                release = resolve;
+            });
+            tail[engine] = prior.then(() => {
+                return held;
+            }, () => {
+                return held;
+            });
+            return prior.then(job, job).finally(() => {
+                release();
+            });
+        }
+    });
+}

package/src/application/mcp/mcpObserve.js

@@ -72,7 +72,7 @@ function settle(outcome) {
 }
 
 /**
- * Times one tool call, counts it, and tracks the engine gauge.
+ * Times one tool call after the engine slot is held.
  *
  * @param {string} name - tool name
  * @param {object} args - tool arguments
@@ -82,9 +82,9 @@ function settle(outcome) {
  * @returns {Promise<object>} tool result
  *
  * @example
- *   trackedTool('state', {}, {}, () => ({ content: [] }), ctx);
+ *   invokeTool('state', {}, {}, () => ({ content: [] }), ctx);
  */
-async function trackedTool(name, args, extra, cb, ctx) {
+async function invokeTool(name, args, extra, cb, ctx) {
     const engine = engineOf(name);
     const started = Date.now();
     ctx.metrics.begin(engine);
@@ -94,6 +94,32 @@ async function trackedTool(name, args, extra, cb, ctx) {
     return settle(outcome);
 }
 
+/**
+ * Times one tool call, counts it, and tracks the engine gauge.
+ *
+ * SQL engines wait for the previous query on that engine so the in-flight
+ * gauge stays at one. Named plant tools are not queued.
+ *
+ * @param {string} name - tool name
+ * @param {object} args - tool arguments
+ * @param {object} extra - SDK extra
+ * @param {Function} cb - tool callback
+ * @param {object} ctx - journal context
+ * @returns {Promise<object>} tool result
+ *
+ * @example
+ *   trackedTool('state', {}, {}, () => ({ content: [] }), ctx);
+ */
+function trackedTool(name, args, extra, cb, ctx) {
+    const engine = engineOf(name);
+    if (engine === 'plant') {
+        return invokeTool(name, args, extra, cb, ctx);
+    }
+    return ctx.flight.run(engine, () => {
+        return invokeTool(name, args, extra, cb, ctx);
+    });
+}
+
 /**
  * Times one resource read.
  *

package/src/application/mcp/mcpResources.js

@@ -1,3 +1,5 @@
+import { clickhouseSchema, postgresSchema } from './mcpSchema.js';
+
 /**
  * Parent path of a node, or an empty string at the root.
  *
@@ -78,29 +80,69 @@ function body(uri, payload) {
 }
 
 /**
- * Registers plant topology and source bindings.
+ * Enumerates catalog entries without knowing their vocabulary.
  *
- * Topology has paths, kinds, titles, and liveness. Bindings map a path to a
- * topic and a unit. Gateway topics are not part of topology.
+ * @param {object} [catalog] - tagCatalog with entries()
+ * @returns {Array<object>} entries
+ *
+ * @example
+ *   tags({ entries() { return []; } });
+ */
+function tags(catalog) {
+    if (catalog && typeof catalog.entries === 'function') {
+        return catalog.entries();
+    }
+    return [];
+}
+
+/**
+ * Registers one JSON resource.
  *
  * @param {object} server - McpServer
- * @param {object} tree - namespaceTree
+ * @param {string} name - resource name
+ * @param {string} uri - resource URI
+ * @param {string} description - short list description
+ * @param {Function} payload - body factory
  * @returns {void}
  *
  * @example
- *   registerResources(server, tree);
+ *   publish(server, 'topology', 'plant://topology', 'Paths', () => []);
  */
-export default function registerResources(server, tree) {
-    server.registerResource('topology', 'plant://topology', {
-        description: 'Paths, kinds, titles, and liveness',
+function publish(server, name, uri, description, payload) {
+    server.registerResource(name, uri, {
+        description,
         mimeType: 'application/json'
     }, () => {
-        return body('plant://topology', topology(tree));
+        return body(uri, payload());
     });
-    server.registerResource('bindings', 'plant://bindings', {
-        description: 'Source topic and unit for each bound path',
-        mimeType: 'application/json'
-    }, () => {
-        return body('plant://bindings', bindings(tree));
+}
+
+/**
+ * Registers plant topology, bindings, tags, and storage schemas.
+ *
+ * Topology has paths, kinds, titles, and liveness. Bindings map a path to a
+ * topic and a unit. Tags enumerate the catalog the plant package supplied.
+ * Schema resources list scada migration tables. Gateway topics stay out of
+ * topology. Operators omit card_uid. kind is opaque.
+ *
+ * @param {object} server - McpServer
+ * @param {object} tree - namespaceTree
+ * @param {object} [catalog] - tagCatalog with entries()
+ * @returns {void}
+ *
+ * @example
+ *   registerResources(server, tree, catalog);
+ */
+export default function registerResources(server, tree, catalog) {
+    publish(server, 'topology', 'plant://topology', 'Paths, kinds, titles, and liveness', () => {
+        return topology(tree);
+    });
+    publish(server, 'bindings', 'plant://bindings', 'Source topic and unit for each bound path', () => {
+        return bindings(tree);
+    });
+    publish(server, 'tags', 'plant://tags', 'Tag catalog entries from the plant package', () => {
+        return tags(catalog);
     });
+    publish(server, 'schema-postgres', 'plant://schema/postgres', 'Postgres tables from scada migrations', postgresSchema);
+    publish(server, 'schema-clickhouse', 'plant://schema/clickhouse', 'ClickHouse scada.metrics', clickhouseSchema);
 }

package/src/application/mcp/mcpSchema.js

@@ -0,0 +1,98 @@
+/**
+ * Column list for one schema table.
+ *
+ * @param {string} name - table name
+ * @param {Array<object>} columns - name and type
+ * @param {Array<string>} [notes] - short notes
+ * @returns {object} table
+ *
+ * @example
+ *   table('alerts', [{ name: 'id', type: 'integer' }]);
+ */
+function table(name, columns, notes) {
+    if (!notes) {
+        return { columns, name };
+    }
+    return { columns, name, notes };
+}
+
+/**
+ * Postgres tables from scada migrations, without operator credentials.
+ *
+ * kind is an opaque string. Plant brigade tables are not listed.
+ *
+ * @returns {object} schema body
+ *
+ * @example
+ *   postgresSchema().tables[0].name;
+ */
+export function postgresSchema() {
+    return {
+        tables: [
+            table('segments', [
+                { name: 'machine', type: 'text' },
+                { name: 'name', type: 'text' },
+                { name: 'start_time', type: 'timestamptz' },
+                { name: 'end_time', type: 'timestamptz' },
+                { name: 'duration', type: 'float' },
+                { name: 'options', type: 'text' },
+                { name: 'tags', type: 'text' },
+                { name: 'properties', type: 'text' },
+                { name: 'resolved', type: 'boolean' },
+                { name: 'consumed', type: 'boolean' },
+                { name: 'kind', type: 'text' },
+                { name: 'updated_at', type: 'timestamptz' }
+            ], ['kind is an opaque string']),
+            table('operations', [
+                { name: 'machine', type: 'text' },
+                { name: 'occurred_at', type: 'timestamptz' },
+                { name: 'kind', type: 'text' },
+                { name: 'key', type: 'text' },
+                { name: 'payload', type: 'jsonb' }
+            ], ['kind is an opaque string']),
+            table('alerts', [
+                { name: 'id', type: 'integer' },
+                { name: 'name', type: 'text' },
+                { name: 'message', type: 'text' },
+                { name: 'machine', type: 'text' },
+                { name: 'severity', type: 'text' },
+                { name: 'timestamp', type: 'timestamptz' },
+                { name: 'acknowledged', type: 'boolean' }
+            ]),
+            table('user_decisions', [
+                { name: 'machine', type: 'text' },
+                { name: 'start_time', type: 'timestamptz' },
+                { name: 'username', type: 'text' },
+                { name: 'payload', type: 'text' },
+                { name: 'operator_id', type: 'integer' },
+                { name: 'decided_at', type: 'timestamptz' }
+            ]),
+            table('operators', [
+                { name: 'id', type: 'integer' },
+                { name: 'first_name', type: 'text' },
+                { name: 'last_name', type: 'text' },
+                { name: 'display_name', type: 'text' }
+            ])
+        ]
+    };
+}
+
+/**
+ * ClickHouse metrics table. topic is the only series key.
+ *
+ * @returns {object} schema body
+ *
+ * @example
+ *   clickhouseSchema().tables[0].name;
+ */
+export function clickhouseSchema() {
+    return {
+        tables: [
+            table('scada.metrics', [
+                { name: 'topic', type: 'String' },
+                { name: 'ts', type: 'DateTime64(3)' },
+                { name: 'value', type: 'Float64' }
+            ], ['topic is the only series key'])
+        ]
+    };
+}

package/src/domain/span/coverageOverlay.js

@@ -0,0 +1,164 @@
+/**
+ * Reads epoch milliseconds from a number, Date, or parseable string.
+ *
+ * @param {Date|number|string} value - instant
+ * @returns {number} epoch milliseconds, or NaN
+ *
+ * @example
+ *   epoch('2024-11-02T03:04:05.137Z');
+ */
+function epoch(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    return Date.parse(String(value));
+}
+
+/**
+ * Converts an instant and rejects values that are not a time.
+ *
+ * @param {Date|number|string} value - instant
+ * @returns {number} epoch milliseconds
+ *
+ * @example
+ *   stamp('2024-11-02T03:04:05.137Z');
+ */
+function stamp(value) {
+    const at = epoch(value);
+    if (Number.isNaN(at)) {
+        throw new Error(`Coverage overlay instant is not a time: ${value}`);
+    }
+    return at;
+}
+
+/**
+ * Reads a segment bound from one of the accepted field names.
+ *
+ * @param {object} row - segment
+ * @param {Array<string>} names - field names
+ * @returns {Date|number|string} instant
+ *
+ * @example
+ *   field({ start_time: '2024-11-02T03:04:05.137Z' }, ['start_time', 'from']);
+ */
+function field(row, names) {
+    const name = names.find((key) => {
+        return Object.hasOwn(row, key);
+    });
+    if (!name) {
+        throw new Error(`Coverage overlay bound is missing: ${names.join(',')}`);
+    }
+    return row[name];
+}
+
+/**
+ * Normalizes a timeline row to epoch bounds and a name.
+ *
+ * @param {object} row - segment
+ * @returns {{from: number, name: string, to: number}} interval
+ *
+ * @example
+ *   bounds({ name: 'off', start_time: 0, end_time: 1 });
+ */
+function bounds(row) {
+    return {
+        from: stamp(field(row, ['start_time', 'from', 'start'])),
+        name: typeof row.name === 'string' ? row.name : '',
+        to: stamp(field(row, ['end_time', 'to', 'end']))
+    };
+}
+
+/**
+ * Unique sorted cut points of a span and the intervals that cross it.
+ *
+ * @param {object} span - coverage span
+ * @param {Array<object>} rows - normalized intervals
+ * @returns {Array<number>} epochs
+ *
+ * @example
+ *   cuts({ from: 'a', to: 'b' }, []);
+ */
+function cuts(span, rows) {
+    const start = stamp(span.from);
+    const stop = stamp(span.to);
+    const marks = [start, stop];
+    rows.forEach((row) => {
+        if (row.from > start && row.from < stop) {
+            marks.push(row.from);
+        }
+        if (row.to > start && row.to < stop) {
+            marks.push(row.to);
+        }
+    });
+    return Array.from(new Set(marks)).sort((left, right) => {
+        return left - right;
+    });
+}
+
+/**
+ * Timeline name that overlaps an open interval, or an empty string.
+ *
+ * @param {Array<object>} rows - normalized intervals
+ * @param {number} from - start epoch
+ * @param {number} to - end epoch
+ * @returns {string} name
+ *
+ * @example
+ *   title([{ from: 0, name: 'off', to: 10 }], 0, 10);
+ */
+function title(rows, from, to) {
+    const hit = rows.find((row) => {
+        return row.from < to && row.to > from;
+    });
+    if (!hit) {
+        return '';
+    }
+    return hit.name;
+}
+
+/**
+ * Splits one coverage span on overlapping timeline names.
+ *
+ * @param {object} span - coverage span
+ * @param {Array<object>} rows - normalized intervals
+ * @returns {Array<object>} painted spans
+ *
+ * @example
+ *   paint({ from: 'a', status: 'present', to: 'b' }, []);
+ */
+function paint(span, rows) {
+    const marks = cuts(span, rows);
+    return marks.slice(0, -1).map((from, index) => {
+        const to = marks[index + 1];
+        return {
+            from: new Date(from).toISOString(),
+            phase: title(rows, from, to),
+            status: span.status,
+            to: new Date(to).toISOString()
+        };
+    });
+}
+
+/**
+ * Paints overlapping timeline names onto coverage spans.
+ *
+ * coverageSpans stays a status classifier. This join splits a span wherever
+ * a timeline interval starts or ends and copies that interval name as phase.
+ *
+ * @param {Array<object>} spans - coverage spans
+ * @param {Array<object>} segments - timeline rows
+ * @returns {Array<object>} spans with phase
+ *
+ * @example
+ *   coverageOverlay([{ from, status: 'present', to }], [{ name, start_time, end_time }]);
+ */
+export default function coverageOverlay(spans, segments) {
+    const rows = (Array.isArray(segments) ? segments : []).map(bounds);
+    const list = Array.isArray(spans) ? spans : [];
+    return list.flatMap((span) => {
+        return paint(span, rows);
+    });
+}