@yarkivaev/scada 2.3.47 → 2.3.49

package/README.md

@@ -200,14 +200,18 @@ import stateDataFake from '@yarkivaev/scada/stateDataFake';
 
 ## Package boundary
 
-| This package (`@yarkivaev/scada`) | Downstream plant package |
+**Hard rule:** this package is factory-agnostic. It must not contain Sokol melting/bath domain, chem-analysis UI, HMI copy (e.g. Болото), `weight_after` fold semantics, or plant-specific sensors/routes. Those belong in `sokol-scada` (or another plant package).
+
+Opaque operation `kind` strings and generic ports (`latestForMachine`, list/upsert/stream) are allowed; never treat a kind as a first-class domain type here.
+
+| This package (`@yarkivaev/scada`) | Downstream plant package (`sokol-scada`, …) |
 |------------------------|--------------------------|
-| Generic plant, timeline, alerts, ingest | Site domain, sensors, HMI strings, tag taxonomy |
+| Generic plant, shop, machine, timeline, alerts, operations ports | Melting bath, chem, cycles HMI, site sensors |
 | Empty/injectable alert `translations` | Localized rule messages |
-| Opaque operation `kind` strings | Site-specific kinds (`sample`, `load`, …) |
-| `plantApi`, `siteServer`, `supervisorSink` | Site bins and routes |
+| Opaque operation `kind` strings | Site kinds (`bath`, `chem`, …) and fold/prefix logic |
+| `plantApi`, `siteServer`, `supervisorSink` | Site bins, routes, `bathSensor`, reports |
 | Export ports `Query` / `Stream` / `Sink` / `Job` | Export jobs + destination adapters |
-| ClickHouse + PG adapters | Plant wiring (`metricsPlant`, shops, machines) |
+| ClickHouse + PG adapters | Plant wiring (`sokolPlant` / `edgePlant`) |
 
 Depend on a pinned version (`"@yarkivaev/scada": "…#v2.3.46"`), not a local path, in downstream packages.
 

package/db/migrations/V0006__operations_machine_kind_time.sql

@@ -0,0 +1,2 @@
+CREATE INDEX IF NOT EXISTS idx_operations_machine_kind_time
+    ON operations (machine, kind, occurred_at);

package/package.json

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

package/src/application/plantOperations.js

@@ -6,9 +6,9 @@ import pubsub from '../domain/shared/pubsub.js';
  *
  * Optional kindSources inject non-PG kinds into listForMachine merges.
  *
- * @param {object} persistence - operations store with upsert, get, remove, listForMachine
+ * @param {object} persistence - operations store with upsert, get, remove, listForMachine, latestForMachine
  * @param {object} [kindSources] - map of kind to { list(machineId, range) }
- * @returns {object} operations with listForMachine, upsert, get, remove, and stream
+ * @returns {object} operations with listForMachine, latestForMachine, upsert, get, remove, and stream
  *
  * @example
  *   const ops = plantOperations(dataAccess.operations, { temp: temperaturePort });

package/src/domain/operation/operations.js

@@ -32,15 +32,17 @@ function resolveKinds(kinds, sources) {
  *
  * listForMachine merges requested kinds from injectable sources and Postgres,
  * sorted by occurred_at. Omitted kinds default to injectable source keys.
+ * latestForMachine reads only from persistence (single kind).
  *
- * @param {object} persistence - store with upsert, get, remove, listForMachine
+ * @param {object} persistence - store with upsert, get, remove, listForMachine, latestForMachine
  * @param {object} bus - pubsub instance with stream and emit methods
  * @param {object} [kindSources] - map of kind to { list(machineId, range) }
- * @returns {object} operations with listForMachine, upsert, get, remove, stream
+ * @returns {object} operations with listForMachine, latestForMachine, upsert, get, remove, stream
  *
  * @example
  *   const ops = operations(store, bus, { temp: temperaturePort });
- *   await ops.listForMachine('m1', ['chem', 'temp'], { from: new Date() });
+ *   await ops.listForMachine('m1', ['sample', 'temp'], { from: new Date() });
+ *   await ops.latestForMachine('m1', 'sample', { to: new Date() });
  *   await ops.remove('m1', 'nb-1');
  */
 export default function operations(persistence, bus, kindSources) {
@@ -59,6 +61,9 @@ export default function operations(persistence, bus, kindSources) {
                 });
             });
         },
+        latestForMachine(machineId, kind, bound) {
+            return persistence.latestForMachine(machineId, kind, bound);
+        },
         upsert(item) {
             const updatedAt = new Date();
             const row = stampRow(item, updatedAt);

package/src/infrastructure/client/machineClient.js

@@ -48,7 +48,7 @@ function rangeQuery(options) {
  * @example
  *   const machine = machineClient(baseUrl, 'm1', fetch, EventSource, logger);
  *   const info = await machine.info();
- *   await machine.createOperation({ kind: 'bath', payload: { action: 'load' } });
+ *   await machine.createOperation({ kind: 'load', payload: { action: 'add' } });
  *   await machine.updateOperation(key, { payload: { action: 'load' } });
  *   await machine.deleteOperation(key);
  */

package/src/infrastructure/client/machineOperationsClient.js

@@ -121,7 +121,7 @@ function deleteRequest(request, key, fields) {
  *
  * @example
  *   const ops = machineOperationsClient(baseUrl, request, EventSource, logger);
- *   await ops.createOperation({ kind: 'bath', payload: {}, operatorId: 2 });
+ *   await ops.createOperation({ kind: 'load', payload: {}, operatorId: 2 });
  *   await ops.operationDecisions(key);
  */
 export default function machineOperationsClient(baseUrl, request, eventSource, logger) {

package/src/infrastructure/http/plant/json/operationJson.js

@@ -12,7 +12,7 @@ function iso(value) {
  * @returns {object} API item with external_key and source_updated_at
  *
  * @example
- *   operationJson({ key: 'nb-1', occurred_at: new Date(), kind: 'chem', payload: {}, machine: 'm1' });
+ *   operationJson({ key: 'nb-1', occurred_at: new Date(), kind: 'sample', payload: {}, machine: 'm1' });
  */
 export default function operationJson(row) {
     const occurred = iso(row.occurred_at);

package/src/infrastructure/messaging/ownership/httpOperations.js

@@ -45,7 +45,7 @@ async function readJson(res) {
  *
  * @example
  *   const port = httpOperations({ baseUrl: 'http://edge/api/v1' }, 'm2');
- *   await port.create({ kind: 'bath', payload: {}, operatorId: 2 });
+ *   await port.create({ kind: 'load', payload: {}, operatorId: 2 });
  */
 export default function httpOperations(site, machineId) {
     const base = trimBase(site.baseUrl);

package/src/infrastructure/persistence/memory/operations.js

@@ -37,6 +37,41 @@ function filterList(store, machineId, kind, range) {
     });
 }
 
+/**
+ * Picks the latest matching row for a machine and kind at a time bound.
+ *
+ * @param {object} store - shared mutable store with operations array
+ * @param {string} machineId - machine identifier
+ * @param {string} kind - operation kind
+ * @param {{ to?: Date, before?: Date }} bound - inclusive to or exclusive before
+ * @returns {object|null} latest row or null
+ */
+function filterLatest(store, machineId, kind, bound) {
+    const range = bound || {};
+    const before = range.before ? new Date(range.before).getTime() : null;
+    const to = range.to ? new Date(range.to).getTime() : null;
+    const matches = store.operations.filter((row) => {
+        if (row.machine !== machineId || row.kind !== kind) {
+            return false;
+        }
+        const at = new Date(row.occurred_at).getTime();
+        if (before !== null && at >= before) {
+            return false;
+        }
+        if (to !== null && at > to) {
+            return false;
+        }
+        return true;
+    }).sort((left, right) => {
+        const delta = new Date(right.occurred_at) - new Date(left.occurred_at);
+        if (delta !== 0) {
+            return delta;
+        }
+        return String(right.key).localeCompare(String(left.key));
+    });
+    return matches[0] || null;
+}
+
 /**
  * In-memory operations state port for tests and local runs.
  *
@@ -82,6 +117,9 @@ export default function operationStateMemory(store) {
         },
         listForMachine(machineId, kind, range) {
             return Promise.resolve(filterList(store, machineId, kind, range));
+        },
+        latestForMachine(machineId, kind, bound) {
+            return Promise.resolve(filterLatest(store, machineId, kind, bound));
         }
     };
 }

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

@@ -38,6 +38,33 @@ function listForMachine(pool, machineId, kind, range) {
     });
 }
 
+/**
+ * Loads the latest operation for a machine and kind at or before a bound.
+ *
+ * @param {object} pool - pg pool
+ * @param {string} machineId - machine identifier
+ * @param {string} kind - operation kind
+ * @param {{ to?: Date, before?: Date }} bound - inclusive to or exclusive before
+ * @returns {Promise<object|null>} latest row or null
+ */
+function latestForMachine(pool, machineId, kind, bound) {
+    const range = bound || {};
+    let sql = `SELECT machine, occurred_at, kind, key, payload
+        FROM operations WHERE machine = $1 AND kind = $2`;
+    const prm = [machineId, kind];
+    if (range.before) {
+        prm.push(range.before);
+        sql += ` AND occurred_at < $${prm.length}`;
+    } else if (range.to) {
+        prm.push(range.to);
+        sql += ` AND occurred_at <= $${prm.length}`;
+    }
+    sql += ' ORDER BY occurred_at DESC, key DESC LIMIT 1';
+    return pool.query(sql, prm).then((result) => {
+        return result.rows[0] || null;
+    });
+}
+
 function missing(machineId, key) {
     return new Error(`operation '${key}' not found for machine '${machineId}'`);
 }
@@ -70,11 +97,12 @@ async function removeOperation(pool, machineId, key) {
  * PostgreSQL operations persistence port for generic machine operations.
  *
  * @param {object} pool - pg pool
- * @returns {object} operations port with upsert, get, remove, and listForMachine
+ * @returns {object} operations port with upsert, get, remove, listForMachine, latestForMachine
  *
  * @example
  *   const store = operationStatePg(pool);
- *   await store.upsert({ machine: 'm1', key: 'nb-1', kind: 'chem', ... });
+ *   await store.upsert({ machine: 'm1', key: 'nb-1', kind: 'sample', ... });
+ *   await store.latestForMachine('m1', 'sample', { to: new Date() });
  *   await store.remove('m1', 'nb-1');
  */
 export default function operationStatePg(pool) {
@@ -90,6 +118,9 @@ export default function operationStatePg(pool) {
         },
         listForMachine(machineId, kind, range) {
             return listForMachine(pool, machineId, kind, range);
+        },
+        latestForMachine(machineId, kind, bound) {
+            return latestForMachine(pool, machineId, kind, bound);
         }
     };
 }

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

@@ -12,7 +12,7 @@
  *   const catalog = userDecisionsFromPg(pool);
  *   await catalog.insert({
  *     machine: 'm1', startTime: new Date(), username: 'Ivan',
- *     decidedAt: new Date(), payload: { kind: 'operation_op', verb: 'create', key: 'bath:m1:1' }
+ *     decidedAt: new Date(), payload: { kind: 'operation_op', verb: 'create', key: 'op:m1:1' }
  *   });
  */
 function mapRow(row) {

package/src/infrastructure/sync/operationCodec.js

@@ -55,8 +55,8 @@ async function decode(parsed, collector) {
  *
  * @example
  *   const codec = operationCodec(collector);
- *   await codec.accept(Buffer.from('{"machine":"m1","occurred_at":"2024-06-01T10:00:00.000Z","kind":"chem","external_key":"nb-1","payload":{}}'));
- *   await codec.accept(Buffer.from('{"type":"deleted","machine":"m1","occurred_at":"2024-06-01T10:00:00.000Z","kind":"bath","external_key":"k"}'));
+ *   await codec.accept(Buffer.from('{"machine":"m1","occurred_at":"2024-06-01T10:00:00.000Z","kind":"sample","external_key":"nb-1","payload":{}}'));
+ *   await codec.accept(Buffer.from('{"type":"deleted","machine":"m1","occurred_at":"2024-06-01T10:00:00.000Z","kind":"load","external_key":"k"}'));
  */
 export default function operationCodec(collector) {
     if (!collector || typeof collector.accept !== 'function') {

package/src/infrastructure/sync/operationSyncSink.js

@@ -8,8 +8,8 @@ import processingErrorLog from '../ingest/processingErrorLog.js';
  *
  * @example
  *   const sink = operationSyncSink(dataAccess.operations);
- *   await sink.accept({ machine: 'm1', occurred_at: new Date(), kind: 'chem', key: 'nb-1', payload: {} });
- *   await sink.remove({ machine: 'm1', kind: 'chem', key: 'nb-1', occurred_at: new Date() });
+ *   await sink.accept({ machine: 'm1', occurred_at: new Date(), kind: 'sample', key: 'nb-1', payload: {} });
+ *   await sink.remove({ machine: 'm1', kind: 'sample', key: 'nb-1', occurred_at: new Date() });
  */
 export default function operationSyncSink(operations) {
     return {