@yarkivaev/scada 2.3.86 → 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`, `sqlGuard` | Analytics MCP, path index, coverage spans, 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,8 @@ 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';
 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.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/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/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/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/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);
+    });
+}

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 = [];