@yarkivaev/scada 2.3.69 → 2.3.70

package/package.json

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

package/src/infrastructure/client/machineClient.js

@@ -98,6 +98,9 @@ export default function machineClient(baseUrl, machineId, fetcher, eventSource,
             if (options && options.step) {
                 params.set('step', String(options.step));
             }
+            if (options && options.mode) {
+                params.set('mode', options.mode);
+            }
             const qs = params.toString();
             return request(`/measurements${qs ? `?${qs}` : ''}`);
         },

package/src/infrastructure/http/plant/routes/measurementRead.js

@@ -0,0 +1,37 @@
+/**
+ * Reads a downsampled series, rising prefixes, or level changes.
+ *
+ * @param {object} sensor - machine sensor
+ * @param {{start: Date, end: Date}} range - query window
+ * @param {number} step - downsample step in ms
+ * @param {string} [mode] - rises or changes
+ * @returns {Promise<Array>} series rows
+ */
+export default function measurementRead(sensor, range, step, mode) {
+    if (mode === 'rises') {
+        return sensor.rises(range);
+    }
+    if (mode === 'changes') {
+        return sensor.changes(range);
+    }
+    return sensor.measurements(range, step);
+}
+
+/**
+ * Packs one sensor series into the measurements JSON item.
+ *
+ * @param {string} key - sensor key
+ * @param {object} sensor - machine sensor
+ * @param {Array<{timestamp: Date, value: number, unit: string}>} rows - series
+ * @returns {{key: string, name: string, unit: string, values: Array}} item
+ */
+export function measurementItem(key, sensor, rows) {
+    const unit = rows.length > 0 ? rows[0].unit : '';
+    const values = rows.map((row) => {
+        return {
+            timestamp: row.timestamp.toISOString(),
+            value: row.value
+        };
+    });
+    return { key, name: sensor.name(), unit, values };
+}

package/src/infrastructure/http/plant/routes/measurementRoute.js

@@ -1,5 +1,6 @@
 import machineInPlant from '../../../../application/machineInPlant.js';
 import { jsonResponse, route, timeExpression } from '@yarkivaev/simple-server';
+import measurementRead, { measurementItem } from './measurementRead.js';
 
 /**
  * Measurement routes factory.
@@ -13,6 +14,31 @@ import { jsonResponse, route, timeExpression } from '@yarkivaev/simple-server';
  * @example
  *   const routes = measurementRoute('/api/v1', plant, clock);
  */
+/**
+ * Collects measurement items for the requested keys and mode.
+ *
+ * @param {object} machine - plant machine
+ * @param {object} query - HTTP query
+ * @param {function} clock - time provider
+ * @param {function} beginning - range floor
+ * @returns {Promise<Array>} items
+ */
+async function measure(machine, query, clock, beginning) {
+    const requested = query.keys ? query.keys.split(',') : Object.keys(machine.sensors);
+    const keys = requested.filter((key) => {
+        return machine.sensors[key];
+    });
+    const from = timeExpression(query.from || 'now-1M', clock, beginning).resolve();
+    const to = timeExpression(query.to || 'now', clock, beginning).resolve();
+    const step = query.step ? parseInt(query.step, 10) * 1000 : 1000;
+    const range = { start: from, end: to };
+    return await Promise.all(keys.map(async (key) => {
+        const sensor = machine.sensors[key];
+        const rows = await measurementRead(sensor, range, step, query.mode);
+        return measurementItem(key, sensor, rows);
+    }));
+}
+
 export default function measurementRoute(basePath, plant, clock) {
     function beginning() {
         return new Date(clock().getTime() - 30 * 24 * 60 * 60 * 1000);
@@ -34,25 +60,7 @@ export default function measurementRoute(basePath, plant, clock) {
                     jsonResponse({ items: [] }).send(res);
                     return;
                 }
-                const requested = query.keys ? query.keys.split(',') : Object.keys(machine.sensors);
-                const keys = requested.filter((key) => {return machine.sensors[key]});
-                const fromExpr = query.from || 'now-1M';
-                const toExpr = query.to || 'now';
-                const from = timeExpression(fromExpr, clock, beginning).resolve();
-                const to = timeExpression(toExpr, clock, beginning).resolve();
-                const step = query.step ? parseInt(query.step, 10) * 1000 : 1000;
-                const range = { start: from, end: to };
-                const promises = keys.map(async (key) => {
-                    const sensor = machine.sensors[key];
-                    const measurements = await sensor.measurements(range, step);
-                    const unit = measurements.length > 0 ? measurements[0].unit : '';
-                    const values = measurements.map((row) => {return {
-                        timestamp: row.timestamp.toISOString(),
-                        value: row.value
-                    }});
-                    return { key, name: sensor.name(), unit, values };
-                });
-                const items = await Promise.all(promises);
+                const items = await measure(machine, query, clock, beginning);
                 jsonResponse({ items }).send(res);
             }
         )

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

@@ -0,0 +1,59 @@
+/**
+ * Level changes of one ClickHouse metric, including the sample held at the start.
+ *
+ * Heartbeat repeats of the same value stay in the table and out of the result.
+ *
+ * @example
+ *   await clickhouseChanges(conn, 'm1/flag', { start, end }, '');
+ *
+ * @param {object} connection - ClickHouse connection with query method
+ * @param {string} topic - metric topic
+ * @param {{start: Date, end: Date}} range - inclusive window
+ * @param {string} unit - measurement unit
+ * @returns {Promise<Array<{timestamp: Date, value: number, unit: string}>>} changes
+ */
+function formatDateTime(date) {
+    return date.toISOString().replace('Z', '').replace('T', ' ');
+}
+
+const CHANGES_SQL = `WITH prior AS (
+    SELECT ts, value
+    FROM scada.metrics
+    WHERE topic = {topic:String} AND ts < {start:DateTime64(3)}
+    ORDER BY ts DESC
+    LIMIT 1
+), windowed AS (
+    SELECT ts, value
+    FROM scada.metrics
+    WHERE topic = {topic:String}
+      AND ts >= {start:DateTime64(3)}
+      AND ts <= {end:DateTime64(3)}
+), series AS (
+    SELECT ts, value FROM prior
+    UNION ALL
+    SELECT ts, value FROM windowed
+), lagged AS (
+    SELECT
+        ts,
+        value,
+        row_number() OVER (ORDER BY ts) AS n,
+        lagInFrame(value, 1, NULL) OVER (ORDER BY ts) AS prev
+    FROM series
+)
+SELECT if(ts < {start:DateTime64(3)}, {start:DateTime64(3)}, ts) AS ts, value
+FROM lagged
+WHERE n = 1 OR value != prev
+ORDER BY ts`;
+
+export default async function clickhouseChanges(connection, topic, range, unit) {
+    const rows = await connection.query(CHANGES_SQL, {
+        topic,
+        start: formatDateTime(range.start),
+        end: formatDateTime(range.end)
+    });
+    return rows.map((row) => {
+        return { timestamp: new Date(`${row.ts}Z`), value: row.value, unit };
+    });
+}
+
+export { CHANGES_SQL };

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

@@ -0,0 +1,20 @@
+/**
+ * Latest sample of one ClickHouse metric topic.
+ *
+ * @param {object} connection - ClickHouse connection with query method
+ * @param {string} topic - metric topic
+ * @param {string} unit - measurement unit
+ * @returns {Promise<{found: boolean, timestamp?: Date, value?: number, unit?: string}>} reading
+ */
+export default async function clickhouseLatest(connection, topic, unit) {
+    const rows = await connection.query(
+        `SELECT ts, value FROM scada.metrics
+         WHERE topic = {topic:String}
+         ORDER BY ts DESC LIMIT 1`,
+        { topic }
+    );
+    if (rows.length === 0) {
+        return { found: false };
+    }
+    return { found: true, timestamp: new Date(`${rows[0].ts}Z`), value: rows[0].value, unit };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Prefix sum of 0→1 edges for one ClickHouse metric topic.
+ *
+ * @example
+ *   await clickhouseRises(conn, 'm1/flag', { start, end }, '');
+ *
+ * @param {object} connection - ClickHouse connection with query method
+ * @param {string} topic - metric topic
+ * @param {{start: Date, end: Date}} range - half-open window
+ * @param {string} unit - measurement unit
+ * @returns {Promise<Array<{timestamp: Date, value: number, unit: string}>>} prefixes
+ */
+function formatDateTime(date) {
+    return date.toISOString().replace('Z', '').replace('T', ' ');
+}
+
+const RISES_SQL = `WITH prior AS (
+    SELECT ts, value
+    FROM scada.metrics
+    WHERE topic = {topic:String} AND ts < {start:DateTime64(3)}
+    ORDER BY ts DESC
+    LIMIT 1
+), windowed AS (
+    SELECT ts, value
+    FROM scada.metrics
+    WHERE topic = {topic:String}
+      AND ts >= {start:DateTime64(3)}
+      AND ts < {end:DateTime64(3)}
+), series AS (
+    SELECT ts, value FROM prior
+    UNION ALL
+    SELECT ts, value FROM windowed
+), lagged AS (
+    SELECT
+        ts,
+        value,
+        lagInFrame(value, 1, NULL) OVER (ORDER BY ts) AS prev
+    FROM series
+)
+SELECT ts, sum(1) OVER (ORDER BY ts) AS value
+FROM lagged
+WHERE ts >= {start:DateTime64(3)} AND prev = 0 AND value = 1
+ORDER BY ts`;
+
+export default async function clickhouseRises(connection, topic, range, unit) {
+    const rows = await connection.query(RISES_SQL, {
+        topic,
+        start: formatDateTime(range.start),
+        end: formatDateTime(range.end)
+    });
+    return rows.map((row) => {
+        return { timestamp: new Date(`${row.ts}Z`), value: row.value, unit };
+    });
+}
+
+export { RISES_SQL };

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

@@ -11,7 +11,7 @@
  * @param {string} topic - Metric topic in format '{machine}/{sensor}'
  * @param {string} displayName - Human-readable sensor name
  * @param {string} unit - Measurement unit (e.g., 'V', 'cos(φ)')
- * @returns {object} sensor with name, current, measurements and stream methods
+ * @returns {object} sensor with name, current, measurements, rises, changes and stream methods
  *
  * @example
  *   const sensor = clickhouseSensor(conn, 'm1/voltage', 'Voltage', 'V');
@@ -21,49 +21,27 @@
  *   sensor.stream(since, 1000, callback); // live stream
  */
 import clickhouseStreamHub from './streamHub.js';
-
-function formatDateTime(date) {
-    return date.toISOString().replace('Z', '').replace('T', ' ');
-}
+import clickhouseRises from './rises.js';
+import clickhouseChanges from './changes.js';
+import clickhouseSeries from './series.js';
+import clickhouseLatest from './latest.js';
 
 export default function clickhouseSensor(connection, topic, displayName, unit) {
     return {
         name() {
             return displayName;
         },
-        async current() {
-            const rows = await connection.query(
-                `SELECT ts, value FROM scada.metrics
-                 WHERE topic = {topic:String}
-                 ORDER BY ts DESC LIMIT 1`,
-                { topic }
-            );
-            if (rows.length === 0) {
-                return { found: false };
-            }
-            return { found: true, timestamp: new Date(`${rows[0].ts}Z`), value: rows[0].value, unit };
+        current() {
+            return clickhouseLatest(connection, topic, unit);
         },
-        async measurements(range, step) {
-            const seconds = Math.max(1, Math.floor(step / 1000));
-            const rows = await connection.query(
-                `SELECT
-                    toStartOfInterval(ts, INTERVAL ${seconds} SECOND) as ts,
-                    anyLast(value) as value
-                FROM scada.metrics
-                WHERE topic = {topic:String}
-                  AND ts >= toStartOfInterval({start:DateTime64(3)}, INTERVAL ${seconds} SECOND)
-                  AND ts <= {end:DateTime64(3)}
-                GROUP BY ts
-                ORDER BY ts`,
-                {
-                    topic,
-                    start: formatDateTime(range.start),
-                    end: formatDateTime(range.end)
-                }
-            );
-            return rows.map((row) => {
-                return { timestamp: new Date(`${row.ts}Z`), value: row.value, unit };
-            });
+        measurements(range, step) {
+            return clickhouseSeries(connection, topic, range, step, unit);
+        },
+        rises(range) {
+            return clickhouseRises(connection, topic, range, unit);
+        },
+        changes(range) {
+            return clickhouseChanges(connection, topic, range, unit);
         },
         stream(since, step, callback, clock) {
             return clickhouseStreamHub(connection).watch(topic, since, step, callback, {

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

@@ -0,0 +1,30 @@
+/**
+ * Downsampled ClickHouse metric series for one topic.
+ *
+ * @param {object} connection - ClickHouse connection with query method
+ * @param {string} topic - metric topic
+ * @param {{start: Date, end: Date}} range - inclusive window
+ * @param {number} step - downsample step in ms
+ * @param {string} unit - measurement unit
+ * @returns {Promise<Array<{timestamp: Date, value: number, unit: string}>>} buckets
+ */
+export default async function clickhouseSeries(connection, topic, range, step, unit) {
+    const seconds = Math.max(1, Math.floor(step / 1000));
+    const start = range.start.toISOString().replace('Z', '').replace('T', ' ');
+    const end = range.end.toISOString().replace('Z', '').replace('T', ' ');
+    const rows = await connection.query(
+        `SELECT
+            toStartOfInterval(ts, INTERVAL ${seconds} SECOND) as ts,
+            anyLast(value) as value
+        FROM scada.metrics
+        WHERE topic = {topic:String}
+          AND ts >= toStartOfInterval({start:DateTime64(3)}, INTERVAL ${seconds} SECOND)
+          AND ts <= {end:DateTime64(3)}
+        GROUP BY ts
+        ORDER BY ts`,
+        { topic, start, end }
+    );
+    return rows.map((row) => {
+        return { timestamp: new Date(`${row.ts}Z`), value: row.value, unit };
+    });
+}

package/src/infrastructure/persistence/levelChanges.js

@@ -0,0 +1,28 @@
+/**
+ * Drops repeated samples from an ordered metric series.
+ *
+ * The first row is kept so a window can start from the level already held.
+ * Later rows are kept only when the numeric value changes.
+ *
+ * @example
+ *   levelChanges([
+ *       { ts: new Date('2026-09-30T00:00:00.000Z'), value: 0 },
+ *       { ts: new Date('2026-09-30T00:00:01.000Z'), value: 0 },
+ *       { ts: new Date('2026-09-30T00:00:02.000Z'), value: 1 }
+ *   ]);
+ *
+ * @param {Array<{ts: Date|string, value: number}>} rows - ordered samples
+ * @returns {Array<{ts: Date|string, value: number}>} level changes
+ */
+export default function levelChanges(rows) {
+    const kept = [];
+    let previous;
+    (rows || []).forEach((row) => {
+        const value = Number(row.value);
+        if (kept.length === 0 || value !== previous) {
+            kept.push(row);
+            previous = value;
+        }
+    });
+    return kept;
+}

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

@@ -1,3 +1,7 @@
+import risingPrefixes from '../risingPrefixes.js';
+import levelChanges from '../levelChanges.js';
+import { seriesWindow, topicRows } from '../topicWindow.js';
+
 function bucketKey(tsMs, originMs, stepMs) {
     const slot = Math.floor((tsMs - originMs) / stepMs);
     return originMs + slot * stepMs;
@@ -23,6 +27,28 @@ function rowsForRange(store, topic, startMs, endMs, stepMs) {
     });
 }
 
+function risesOf(rows, topic, startIso, endIso) {
+    const start = new Date(startIso).getTime();
+    const end = new Date(endIso).getTime();
+    const series = seriesWindow(topicRows(rows, topic), start, end, false);
+    return risingPrefixes(series).filter((row) => {
+        const ts = new Date(row.ts).getTime();
+        return ts >= start && ts < end;
+    });
+}
+
+function changesOf(rows, topic, startIso, endIso) {
+    const start = new Date(startIso).getTime();
+    const end = new Date(endIso).getTime();
+    const series = seriesWindow(topicRows(rows, topic), start, end, true);
+    return levelChanges(series).map((row, index) => {
+        if (index === 0 && new Date(row.ts).getTime() < start) {
+            return { ts: new Date(start), value: row.value };
+        }
+        return { ts: row.ts, value: row.value };
+    });
+}
+
 /**
  * In-memory metrics state port for tests and local runs.
  *
@@ -45,6 +71,12 @@ export default function metricsStateMemory(store) {
             const stepSec = Math.max(1, Math.floor(stepMs / 1000));
             return rowsForRange(store, topic, start, end, stepSec * 1000);
         },
+        risesForTopic(topic, startIso, endIso) {
+            return risesOf(store.metrics, topic, startIso, endIso);
+        },
+        changesForTopic(topic, startIso, endIso) {
+            return changesOf(store.metrics, topic, startIso, endIso);
+        },
         pollTopic(topic, afterIso, untilIso) {
             const after = new Date(afterIso).getTime();
             const until = new Date(untilIso).getTime();

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

@@ -9,6 +9,12 @@ export default function metricsStateDisabled() {
         rangeForTopic() {
             return Promise.resolve([]);
         },
+        risesForTopic() {
+            return Promise.resolve([]);
+        },
+        changesForTopic() {
+            return Promise.resolve([]);
+        },
         pollTopic() {
             return Promise.resolve([]);
         },

package/src/infrastructure/persistence/metricsSensor.js

@@ -1,6 +1,4 @@
-function parseTimestamp(ts) {
-    return ts instanceof Date ? ts : new Date(ts);
-}
+import seriesRows, { parseTimestamp } from './seriesRows.js';
 
 function pollStream(spec) {
     const { read, topic, since, step, callback, clock, unit } = spec;
@@ -45,6 +43,12 @@ export function pgMetricsRead(metrics) {
         range(topic, startIso, endIso, stepMs) {
             return metrics.rangeForTopic(topic, startIso, endIso, stepMs);
         },
+        rises(topic, startIso, endIso) {
+            return metrics.risesForTopic(topic, startIso, endIso);
+        },
+        changes(topic, startIso, endIso) {
+            return metrics.changesForTopic(topic, startIso, endIso);
+        },
         poll(topic, afterIso, untilIso) {
             return metrics.pollTopic(topic, afterIso, untilIso);
         }
@@ -84,13 +88,23 @@ export default function metricsSensor(read, topic, displayName, unit) {
                 range.end.toISOString(),
                 step
             );
-            return rows.map((row) => {
-                return {
-                    timestamp: parseTimestamp(row.ts),
-                    value: row.value,
-                    unit
-                };
-            });
+            return seriesRows(rows, unit);
+        },
+        async rises(range) {
+            const rows = await read.rises(
+                topic,
+                range.start.toISOString(),
+                range.end.toISOString()
+            );
+            return seriesRows(rows, unit);
+        },
+        async changes(range) {
+            const rows = await read.changes(
+                topic,
+                range.start.toISOString(),
+                range.end.toISOString()
+            );
+            return seriesRows(rows, unit);
         },
         stream(since, step, callback, clock) {
             return pollStream({ read, topic, since, step, callback, clock, unit });

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

@@ -0,0 +1,30 @@
+/**
+ * Level changes for one Postgres metrics topic, including the held start.
+ *
+ * $1 topic, $2 start, $3 inclusive end. The sample before start seeds lag.
+ *
+ * @returns {string} SQL
+ */
+export default function changesSql() {
+    return `WITH prior AS (
+            SELECT ts, value FROM metrics
+            WHERE topic = $1 AND ts < $2
+            ORDER BY ts DESC LIMIT 1
+        ), windowed AS (
+            SELECT ts, value FROM metrics
+            WHERE topic = $1 AND ts >= $2 AND ts <= $3
+        ), series AS (
+            SELECT ts, value FROM prior
+            UNION ALL
+            SELECT ts, value FROM windowed
+        ), marked AS (
+            SELECT ts, value,
+                   LAG(value) OVER (ORDER BY ts) AS prev,
+                   ROW_NUMBER() OVER (ORDER BY ts) AS n
+            FROM series
+        )
+        SELECT CASE WHEN ts < $2 THEN $2 ELSE ts END AS ts, value
+        FROM marked
+        WHERE n = 1 OR value IS DISTINCT FROM prev
+        ORDER BY ts`;
+}

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

@@ -1,3 +1,8 @@
+import risesSql from './risesSql.js';
+import changesSql from './changesSql.js';
+import queryTopic from './queryTopic.js';
+import rangeSql from './rangeSql.js';
+
 export default function metricsStatePg(pool) {
     return {
         async latestForTopic(topic) {
@@ -7,18 +12,15 @@ export default function metricsStatePg(pool) {
             );
             return result.rows[0] ?? null;
         },
-        async rangeForTopic(topic, startIso, endIso, stepMs) {
+        rangeForTopic(topic, startIso, endIso, stepMs) {
             const seconds = Math.max(1, Math.floor(stepMs / 1000));
-            const sql = `SELECT bucket AS ts, value FROM (
-            SELECT date_bin($1::interval, ts, '1970-01-01'::timestamptz) AS bucket, value,
-                   ROW_NUMBER() OVER (PARTITION BY date_bin($1::interval, ts, '1970-01-01'::timestamptz) ORDER BY ts DESC) AS rn
-            FROM metrics WHERE topic = $2 AND ts >= $3 AND ts <= $4
-        ) sub WHERE rn = 1 ORDER BY ts`;
-            const prm = [`${seconds} seconds`, topic, startIso, endIso];
-            const result = await pool.query(sql, prm);
-            return result.rows.map((row) => {
-                return { ts: row.ts, value: row.value };
-            });
+            return queryTopic(pool, rangeSql(), [`${seconds} seconds`, topic, startIso, endIso]);
+        },
+        risesForTopic(topic, startIso, endIso) {
+            return queryTopic(pool, risesSql(), [topic, startIso, endIso]);
+        },
+        changesForTopic(topic, startIso, endIso) {
+            return queryTopic(pool, changesSql(), [topic, startIso, endIso]);
         },
         async pollTopic(topic, afterIso, untilIso) {
             const result = await pool.query(

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

@@ -0,0 +1,14 @@
+/**
+ * Runs a topic SQL and maps ts/value rows.
+ *
+ * @param {object} pool - Postgres pool
+ * @param {string} sql - query text
+ * @param {Array} params - query params
+ * @returns {Promise<Array<{ts: Date|string, value: number}>>} rows
+ */
+export default async function queryTopic(pool, sql, params) {
+    const result = await pool.query(sql, params);
+    return result.rows.map((row) => {
+        return { ts: row.ts, value: Number(row.value) };
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Downsampled Postgres range for one metrics topic.
+ *
+ * $1 interval, $2 topic, $3 start, $4 end.
+ *
+ * @returns {string} SQL
+ */
+export default function rangeSql() {
+    return `SELECT bucket AS ts, value FROM (
+            SELECT date_bin($1::interval, ts, '1970-01-01'::timestamptz) AS bucket, value,
+                   ROW_NUMBER() OVER (PARTITION BY date_bin($1::interval, ts, '1970-01-01'::timestamptz) ORDER BY ts DESC) AS rn
+            FROM metrics WHERE topic = $2 AND ts >= $3 AND ts <= $4
+        ) sub WHERE rn = 1 ORDER BY ts`;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Prefix sum of 0→1 edges for one Postgres metrics topic.
+ *
+ * $1 topic, $2 start, $3 exclusive end. The sample before start seeds lag.
+ *
+ * @returns {string} SQL
+ */
+export default function risesSql() {
+    return `WITH prior AS (
+            SELECT ts, value FROM metrics
+            WHERE topic = $1 AND ts < $2
+            ORDER BY ts DESC LIMIT 1
+        ), windowed AS (
+            SELECT ts, value FROM metrics
+            WHERE topic = $1 AND ts >= $2 AND ts < $3
+        ), series AS (
+            SELECT ts, value FROM prior
+            UNION ALL
+            SELECT ts, value FROM windowed
+        ), marked AS (
+            SELECT ts, value, LAG(value) OVER (ORDER BY ts) AS prev
+            FROM series
+        )
+        SELECT marked.ts AS ts,
+               SUM(1) OVER (ORDER BY marked.ts) AS value
+        FROM marked
+        WHERE marked.ts >= $2 AND marked.prev = 0 AND marked.value = 1
+        ORDER BY marked.ts`;
+}

package/src/infrastructure/persistence/risingPrefixes.js

@@ -0,0 +1,29 @@
+/**
+ * Builds a prefix sum of 0→1 edges on an ordered numeric series.
+ *
+ * Heartbeat repeats of 1 do not increment. A series that starts already
+ * high does not produce a prefix until a later 0→1 pair.
+ *
+ * @example
+ *   risingPrefixes([
+ *       { ts: new Date('2026-09-30T00:00:00.000Z'), value: 0 },
+ *       { ts: new Date('2026-09-30T00:00:01.000Z'), value: 1 }
+ *   ]);
+ *
+ * @param {Array<{ts: Date|string, value: number}>} rows - ordered samples
+ * @returns {Array<{ts: Date|string, value: number}>} prefix points
+ */
+export default function risingPrefixes(rows) {
+    let previous;
+    let count = 0;
+    const prefixes = [];
+    (rows || []).forEach((row) => {
+        const value = Number(row.value);
+        if (previous === 0 && value === 1) {
+            count += 1;
+            prefixes.push({ ts: row.ts, value: count });
+        }
+        previous = value;
+    });
+    return prefixes;
+}

package/src/infrastructure/persistence/seriesRows.js

@@ -0,0 +1,22 @@
+function parseTimestamp(ts) {
+    return ts instanceof Date ? ts : new Date(ts);
+}
+
+/**
+ * Maps storage rows onto the sensor measurement shape.
+ *
+ * @param {Array<{ts: Date|string, value: number}>} rows - storage rows
+ * @param {string} unit - measurement unit
+ * @returns {Array<{timestamp: Date, value: number, unit: string}>} series
+ */
+export default function seriesRows(rows, unit) {
+    return rows.map((row) => {
+        return {
+            timestamp: parseTimestamp(row.ts),
+            value: row.value,
+            unit
+        };
+    });
+}
+
+export { parseTimestamp };

package/src/infrastructure/persistence/topicWindow.js

@@ -0,0 +1,39 @@
+/**
+ * Orders one topic and splits a prior sample from the requested window.
+ *
+ * @param {Array<{topic: string, ts: Date|string, value: number}>} rows - store
+ * @param {string} topic - metric topic
+ * @returns {Array<{topic: string, ts: Date, value: number}>} time-ordered hits
+ */
+export function topicRows(rows, topic) {
+    return (rows || []).filter((row) => {
+        return row.topic === topic;
+    }).map((row) => {
+        return { topic: row.topic, ts: new Date(row.ts), value: row.value };
+    }).sort((left, right) => {
+        return left.ts.getTime() - right.ts.getTime();
+    });
+}
+
+/**
+ * Preceding sample plus in-window rows for lag-based queries.
+ *
+ * @param {Array<{ts: Date, value: number}>} rows - one topic ordered
+ * @param {number} startMs - window start
+ * @param {number} endMs - window end
+ * @param {boolean} closed - true when the end is inclusive
+ * @returns {Array<{ts: Date, value: number}>} prior plus window
+ */
+export function seriesWindow(rows, startMs, endMs, closed) {
+    const prior = rows.filter((row) => {
+        return row.ts.getTime() < startMs;
+    }).pop();
+    const window = rows.filter((row) => {
+        const ts = row.ts.getTime();
+        if (ts < startMs) {
+            return false;
+        }
+        return closed ? ts <= endMs : ts < endMs;
+    });
+    return prior ? [prior].concat(window) : window;
+}