@yarkivaev/scada 2.4.6 → 2.4.8

package/README.md

@@ -485,3 +485,40 @@ their integration tests live in `src/infrastructure/streams` and are exported as
 `@yarkivaev/scada/streams`. This includes AMQP, MQTT, STOMP, serial, Modbus, Loki,
 PostgreSQL, ClickHouse and SQLite; OPC UA stays in `@yarkivaev/scada/opcua`.
 Plant-specific transformations stay in the plant package.
+
+## Segment transaction batches
+
+`supervisor-sink` can read a plant policy from `SEGMENTS_TX_POLICY_FILE` (JSON).
+Without a policy or `SEGMENTS_TX_*` settings, existing deployments keep their current behaviour.
+Environment values override every policy field, so a ConfigMap update and a Recreate restart
+of the same image can tune persistence without an application release.
+
+| Policy field | Environment override | Default when enabled | Meaning |
+| --- | --- | --- | --- |
+| `enabled` | `SEGMENTS_TX_ENABLED` | `true` | Explicit `false` disables batching and bypasses an obsolete policy path. |
+| `maxMessages` | `SEGMENTS_TX_MAX_MESSAGES` | 32 | Original deliveries per transaction, capped by STOMP prefetch. |
+| `maxBytes` | `SEGMENTS_TX_MAX_BYTES` | 1048576 | Batch payload byte target; a transport-valid oversized delivery runs alone. |
+| `maxWaitMs` | `SEGMENTS_TX_MAX_WAIT_MS` | 100 | Age after which a partial batch becomes eligible to write. |
+| `completedSegments` | `SEGMENTS_TX_COMPLETED_SEGMENTS` | 1 | Flush after this many distinct completed segment keys; `0` disables this trigger. |
+| `concurrency` | `SEGMENTS_TX_CONCURRENCY` | 2 | Concurrent transactions for independent machines. |
+| `timeoutMs` | `SEGMENTS_TX_TIMEOUT_MS` | 10000 | Bounds connection acquisition, statements and COMMIT for a transaction. |
+| `statsIntervalMs` | `SEGMENTS_TX_STATS_INTERVAL_MS` | 10000 | Aggregate transaction log interval; `0` disables it. |
+
+`SEGMENTS_DB_POOL_MAX` controls the owned pool (default 10); transaction concurrency must fit it.
+`STOMP_PREFETCH`, `STOMP_MAX_MESSAGE_BYTES`, `STOMP_MAX_PENDING_BYTES`,
+`STOMP_ACCEPT_TIMEOUT_MS` and `STOMP_STOP_TIMEOUT_MS` remain independently configurable.
+The pending-byte lease remains held until actual commit or rejection. Prefetch, byte limits
+and the partial-batch timer prevent waiting indefinitely for a long segment's end.
+
+Each machine retains FIFO command order and every input command, including pending snapshots,
+terminal transitions, retags and split families. This preserves orphan-close and continuation
+side effects. Different machines can progress independently.
+Every receipt is acknowledged only after its batch commits. A confirmed permanent row error
+rolls the batch back and isolates commands into individual transactions. Uncertain COMMIT,
+connection failure or timeout fences the subscription; RabbitMQ retains unacknowledged deliveries
+for idempotent replay. WAL durability remains enabled.
+
+`[segment-transactions]` JSON logs contain committed message/record counts, COMMIT and rollback
+counts, SQL-call count, and maximum transaction/wait durations. They contain no payloads or tags.
+Compare these counters with RabbitMQ ACK/drain rates and process memory when tuning. More messages
+per batch reduce COMMIT frequency; the number of SQL writes still depends on command semantics.

package/package.json

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

package/src/application/segmentBatchStats.js

@@ -0,0 +1,18 @@
+/** Payload-free transaction counters for comparing configurations on the same image. */
+export default function segmentBatchStats(intervalMs, output = line => { process.stdout.write(line); }, clock = () => { return performance.now(); }) {
+    let started = clock();
+    let totals = { commits: 0, rollbacks: 0, messages: 0, records: 0, sqlCalls: 0, maxTransactionMs: 0, maxWaitMs: 0 };
+    return event => {
+        if (intervalMs === 0) { return; }
+        if (event.committed) {
+            totals.commits += 1;totals.messages += event.messages;totals.records += event.records;totals.sqlCalls += event.sqlCalls;
+            totals.maxTransactionMs = Math.max(totals.maxTransactionMs, event.durationMs);
+            totals.maxWaitMs = Math.max(totals.maxWaitMs, event.waitMs);
+        } else { totals.rollbacks += 1; }
+        const now = clock();
+        if (now - started >= intervalMs) {
+            output(`[segment-transactions] ${JSON.stringify({ intervalMs: now - started, ...totals })}\n`);
+            started = now;totals = { commits: 0, rollbacks: 0, messages: 0, records: 0, sqlCalls: 0, maxTransactionMs: 0, maxWaitMs: 0 };
+        }
+    };
+}

package/src/application/segmentTransactionConfig.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import segmentBatchPolicy from '../infrastructure/ingest/pipelines/segmentBatchPolicy.js';
+
+const variables = { maxMessages: 'MAX_MESSAGES', maxBytes: 'MAX_BYTES', maxWaitMs: 'MAX_WAIT_MS',
+    completedSegments: 'COMPLETED_SEGMENTS', concurrency: 'CONCURRENCY', timeoutMs: 'TIMEOUT_MS', statsIntervalMs: 'STATS_INTERVAL_MS' };
+
+function loadPolicy(env) {
+    const policy = env.SEGMENTS_TX_POLICY_FILE ? JSON.parse(readFileSync(env.SEGMENTS_TX_POLICY_FILE, 'utf8')) : {};
+    if (env.SEGMENTS_TX_ENABLED !== undefined) {
+        if (!['true', 'false'].includes(env.SEGMENTS_TX_ENABLED)) { throw new TypeError('SEGMENTS_TX_ENABLED must be true or false'); }
+        policy.enabled = env.SEGMENTS_TX_ENABLED === 'true';
+    }
+    for (const [key, suffix] of Object.entries(variables)) {
+        const value = env[`SEGMENTS_TX_${suffix}`];
+        if (value !== undefined) { policy[key] = Number(value); }
+    }
+    return policy;
+}
+/** Plant policy supplies defaults; a ConfigMap can override every operational setting. */
+export default function segmentTransactionConfig(env, poolMax) {
+    if (env.SEGMENTS_TX_ENABLED === 'false') { return { enabled: false }; }
+    if (!env.SEGMENTS_TX_POLICY_FILE && !Object.keys(env).some(key => {return key.startsWith('SEGMENTS_TX_')})) { return { enabled: false }; }
+    const result = segmentBatchPolicy(loadPolicy(env));
+    if (result.enabled && result.concurrency > poolMax) { throw new TypeError('Transaction concurrency exceeds SEGMENTS_DB_POOL_MAX'); }
+    return result;
+}

package/src/application/supervisorSink.js

@@ -1,4 +1,6 @@
 import ingestHealth from './ingestHealth.js';
+import segmentTransactionConfig from './segmentTransactionConfig.js';
+import segmentBatchStats from './segmentBatchStats.js';
 import segmentPipeline, {
     segmentsIngestDestination
 } from '../infrastructure/ingest/pipelines/segmentPipeline.js';
@@ -34,7 +36,9 @@ export function readDeploymentConfig(env) {
     if (!Number.isSafeInteger(prefetch) || prefetch < 1) {
         throw new Error('STOMP_PREFETCH must be a positive safe integer');
     }
+    const dbPoolMax = milliseconds(env, 'SEGMENTS_DB_POOL_MAX', 10);
     return {
+        dbPoolMax,
         stomp: env.STOMP_URL,
         postgres: env.POSTGRES_URL,
         postgresAdmin: env.POSTGRES_ADMIN_URL,
@@ -50,6 +54,9 @@ export function readDeploymentConfig(env) {
         requestTimeoutMs: parseRequestTimeoutMs(env.REQUEST_TIMEOUT_MS),
         pipelines: env.COLLECTOR_MODE !== 'external' && env.SINK_PIPELINES !== 'false',
         pipeline: {
+            transactions: segmentTransactionConfig(env, dbPoolMax),
+            maxMessageBytes: milliseconds(env, 'STOMP_MAX_MESSAGE_BYTES', 1048576),
+            maxPendingBytes: milliseconds(env, 'STOMP_MAX_PENDING_BYTES', prefetch * 1048576),
             prefetch,
             acceptTimeoutMs: milliseconds(env, 'STOMP_ACCEPT_TIMEOUT_MS', 10000),
             stopTimeoutMs: milliseconds(env, 'STOMP_STOP_TIMEOUT_MS', 5000),
@@ -87,7 +94,8 @@ export default function supervisorSink(env = process.env, options = {}) {
     const cfg = readDeploymentConfig(env);
     const health = ingestHealth(options);
     cfg.pipeline.onFatal = (error) => { health.fail(error); };
-    const pool = holdClient(new pg.Pool({ connectionString: cfg.postgres }));
+    if (cfg.pipeline.transactions.enabled) { cfg.pipeline.onBatch = segmentBatchStats(cfg.pipeline.transactions.statsIntervalMs); }
+    const pool = holdClient(new pg.Pool({ connectionString: cfg.postgres, max: cfg.dbPoolMax }));
     const metricsEnabled = cfg.sinkDbProfile === 'edge';
     const dataAccess = stateDataFromPool(pool, { metricsEnabled });
     return {

package/src/domain/segment/dispatch.js

@@ -9,6 +9,10 @@ import { replaceSplit } from './splitFamily.js';
  * @param {object} record - normalized segment record
  * @returns {Promise<void>}
  */
+async function pendingInClient(segmentSink, closer, record, transaction) {
+    await closer.close(record.machine, record.start_time, record.kind || 'phase', transaction);
+    await segmentSink.write([record], transaction);
+}
 async function persistPending(segmentSink, closer, pool, record) {
     const kind = record.kind || 'phase';
     if (!pool || typeof pool.connect !== 'function') {
@@ -47,36 +51,36 @@ async function persistPending(segmentSink, closer, pool, record) {
  *   const route = segmentDispatch(segmentSink, retag, splitSink, closer, pool);
  *   await route.accept({ type: 'segment', machine: 'm1', start_time: '...', duration: 0 });
  */
-async function acceptFamily(pool, record) {
-    if (!pool || typeof pool.connect !== 'function') {
+async function acceptFamily(pool, record, transaction) {
+    if (!transaction && (!pool || typeof pool.connect !== 'function')) {
         throw new Error('split-family requires a pool');
     }
-    await replaceSplit(pool, record);
+    await replaceSplit(pool, record, transaction);
 }
 
 export default function segmentDispatch(segmentSink, retag, splitSink, closer, pool) {
     return {
-        async accept(record) {
+        async accept(record, transaction) {
             if (record.type === 'retag') {
-                await retag.accept(record);
+                await retag.accept(record, transaction);
                 return;
             }
             if (record.type === 'split') {
-                await splitSink.write([record]);
+                await splitSink.write([record], transaction);
                 return;
             }
             if (record.type === 'split-family') {
-                await acceptFamily(pool, record);
+                await acceptFamily(pool, record, transaction);
                 return;
             }
             if (record.type !== 'segment') {
                 throw new Error(`Segment command type ${record.type} is not defined`);
             }
             if (record.duration !== 0) {
-                await segmentSink.write([record]);
+                await segmentSink.write([record], transaction);
                 return;
             }
-            await persistPending(segmentSink, closer, pool, record);
+            await (transaction ? pendingInClient(segmentSink, closer, record, transaction) : persistPending(segmentSink, closer, pool, record));
         }
     };
 }

package/src/domain/segment/splitFamily.js

@@ -241,8 +241,13 @@ export function splitRows(machine, splits) {
  * @param {object} record - machine, origin millis, pieces
  * @returns {Promise<void>}
  */
-export async function replaceSplit(pool, record) {
+export async function replaceSplit(pool, record, transaction) {
     refuseEmpty(record);
+    if (transaction) {
+        await removeObsolete(transaction, record);
+        await writePieces(transaction, record.pieces);
+        return;
+    }
     const client = await pool.connect();
     try {
         await client.query('BEGIN');

package/src/infrastructure/ingest/codecs/segmentCodec.js

@@ -25,28 +25,25 @@ function familyRecord(parsed) {
     };
 }
 
+/** Decode once before admission so invalid envelopes never enter a transaction batch. */
+export function decodeSegment(raw) {
+    try {
+        const parsed = JSON.parse(raw.payload);
+        return parsed.type === 'split-family' ? familyRecord(parsed) : segmentNormalize(parsed);
+    } catch (error) {
+        error.permanent = true;
+        throw error;
+    }
+}
+
 export default function segmentCodec(collector) {
     if (!collector || typeof collector.accept !== 'function') {
         throw new Error('Collector must have an accept() method');
     }
     return {
         async accept(raw) {
-            try {
-                let parsed;
-                let record;
-                try {
-                    parsed = JSON.parse(raw.payload);
-                    record = parsed.type === 'split-family' ? familyRecord(parsed) : segmentNormalize(parsed);
-                } catch (error) {
-                    error.permanent = true;
-                    throw error;
-                }
-                if (parsed.type === 'split-family') {
-                    await collector.accept(record);
-                    return;
-                }
-                await collector.accept(record);
-            } catch (error) {
+            try { await collector.accept(decodeSegment(raw)); }
+            catch (error) {
                 processingErrorLog('segment_codec', error, { destination: raw.destination, payload: raw.payload });
                 throw error;
             }

package/src/infrastructure/ingest/pipelines/segmentBatch.js

@@ -0,0 +1,157 @@
+import deadline from '../../streams/deadline.js';
+import segmentBatchPolicy from './segmentBatchPolicy.js';
+
+function notify(callback, value) {
+    try { callback?.(value); } catch {
+        // Observers cannot change commit or fencing semantics.
+    }
+}
+function rejectEntries(entries, error) {
+    for (const entry of entries) {
+        for (const receipt of entry.receipts) {
+            if (!receipt.done) { receipt.done = true;receipt.reject(error); }
+        }
+    }
+}
+function abort(state, error) {
+    if (state.stopped) { return; }
+    state.stopped = true;
+    for (const lane of state.lanes.values()) {
+        for (const packet of lane.packets) { clearTimeout(packet.timer);rejectEntries(packet.entries, error); }
+        lane.packets = [];
+    }
+    for (const packet of state.inflight) { rejectEntries(packet.entries, error); }
+    state.ready = [];
+    notify(state.onAbort, error);
+}
+function fail(state, error) {
+    if (state.failed || state.stopped) { return; }
+    state.failed = error;abort(state, error);notify(state.onFatal, error);
+}
+function ackReceipt(state, receipt) {
+    if (!receipt.done) {
+        receipt.done = true;
+        try { if (!state.stopped) { receipt.settle.ack(); } }
+        catch (error) { fail(state, error); }
+        receipt.resolve();
+    }
+}
+function acknowledge(state, entries) {
+    for (const entry of entries) { entry.receipts.forEach(receipt => { ackReceipt(state, receipt); }); }
+}
+function nackReceipt(state, receipt, error) {
+    if (!receipt.done) {
+        receipt.done = true;
+        try { if (!state.stopped) { receipt.settle.nack(!(state.deadLetter && error.permanent)); } }
+        catch (failure) { fail(state, failure); }
+        receipt.reject(error);
+    }
+}
+function refuse(state, entry, error) { entry.receipts.forEach(receipt => { nackReceipt(state, receipt, error); }); }
+function completedKeys(record) {
+    const rows = record.type === 'split-family' ? record.pieces : [record];
+    return rows.filter(row => {return ['segment', 'split'].includes(row.type) && row.duration > 0})
+        .map(row => {return `${row.machine}\0${row.kind}\0${row.start_time}`});
+}
+function queueReady(state, lane) {
+    if (!state.stopped && !lane.running && !lane.queued && lane.packets[0]?.ready) {
+        lane.queued = true;state.ready.push(lane);state.pump();
+    }
+}
+function ready(state, lane, packet, reason) {
+    if (state.stopped || packet.ready) { return; }
+    packet.ready = true;packet.reason = reason;clearTimeout(packet.timer);queueReady(state, lane);
+}
+function packetFor(state, lane, bytes) {
+    let packet = lane.packets.at(-1);
+    if (packet && !packet.ready && packet.bytes + bytes > state.policy.maxBytes) { ready(state, lane, packet, 'bytes'); }
+    packet = lane.packets.at(-1);
+    if (!packet || packet.ready) {
+        packet = { entries: [], messages: 0, bytes: 0, completed: new Set(), ready: false, createdAt: Date.now() };
+        const pending = packet;
+        packet.timer = setTimeout(() => { ready(state, lane, pending, 'age'); }, state.policy.maxWaitMs);
+        lane.packets.push(packet);
+    }
+    return packet;
+}
+function append(state, lane, input, receipt) {
+    const packet = packetFor(state, lane, input.bytes);
+    packet.entries.push({ record: input.record, receipts: [receipt] });
+    packet.messages += 1;packet.bytes += input.bytes;
+    for (const key of completedKeys(input.record)) { packet.completed.add(key); }
+    if (packet.messages >= state.policy.maxMessages) { ready(state, lane, packet, 'messages'); }
+    else if (packet.bytes >= state.policy.maxBytes) { ready(state, lane, packet, 'bytes'); }
+    else if (state.policy.completedSegments > 0 && packet.completed.size >= state.policy.completedSegments) { ready(state, lane, packet, 'segments'); }
+}
+async function persist(state, entries, packet) {
+    const start = Date.now();
+    const result = await state.write(entries.map(entry => {return entry.record}));
+    acknowledge(state, entries);
+    notify(state.onBatch, { committed: true, messages: entries.reduce((sum, entry) => {return sum + entry.receipts.length}, 0),
+        records: entries.length, durationMs: Date.now() - start, waitMs: start - packet.createdAt,
+        reason: packet.reason, sqlCalls: result?.sqlCalls ?? 0 });
+}
+async function persistOne(state, entry, packet) {
+    if (state.stopped) { throw state.failed ?? new Error('Segment batches stopped'); }
+    try { await persist(state, [entry], packet); }
+    catch (failure) {
+        if (!failure.permanent) { throw failure; }
+        refuse(state, entry, failure);
+    }
+}
+async function runPacket(state, packet) {
+    try { await persist(state, packet.entries, packet); }
+    catch (error) {
+        if (!error.permanent || state.stopped) { throw error; }
+        notify(state.onBatch, { committed: false, messages: packet.messages, records: packet.entries.length, reason: 'rollback' });
+        // Confirmed permanent failure: isolate the bad command after the batch rollback.
+        for (const entry of packet.entries) {
+            // eslint-disable-next-line no-await-in-loop
+            await persistOne(state, entry, packet);
+        }
+    }
+}
+function startPacket(state, lane) {
+    const packet = lane.packets.shift();
+    lane.running = true;state.active += 1;state.inflight.add(packet);
+    const task = Promise.resolve().then(() => { return runPacket(state, packet); }).catch(error => { fail(state, error); }).finally(() => {
+        state.active -= 1;lane.running = false;state.tasks.delete(task);state.inflight.delete(packet);
+        if (lane.packets.length === 0) { state.lanes.delete(lane.machine); }
+        else { queueReady(state, lane); }
+        state.pump();
+    });
+    state.tasks.add(task);
+}
+function pump(state) {
+    while (!state.stopped && state.active < state.policy.concurrency && state.ready.length > 0) {
+        const lane = state.ready.shift();lane.queued = false;
+        if (!lane.running && lane.packets[0]?.ready) { startPacket(state, lane); }
+    }
+}
+
+/** Bounded FIFO machine lanes; each accept retains its lease until commit or rejection. */
+export default function segmentBatch(write, options = {}) {
+    const { prefetch = 32, onFatal, onAbort, onBatch, deadLetter = false, stopTimeoutMs = 5000, ...settings } = options;
+    const policy = segmentBatchPolicy(settings);
+    if (!Number.isSafeInteger(prefetch) || prefetch < 1) { throw new TypeError('prefetch must be a positive integer'); }
+    policy.maxMessages = Math.min(policy.maxMessages, prefetch);
+    const state = { policy, write, onFatal, onAbort, onBatch, deadLetter,
+        lanes: new Map(), ready: [], active: 0, tasks: new Set(), inflight: new Set(), stopped: false, failed: null };
+    state.pump = () => { pump(state); };
+    return {
+        accept(input) {
+            if (state.stopped) { return Promise.reject(state.failed ?? new Error('Segment batches stopped')); }
+            return new Promise((resolve, reject) => {
+                const receipt = { settle: input.settle, resolve, reject, done: false };
+                let lane = state.lanes.get(input.record.machine);
+                if (!lane) { lane = { machine: input.record.machine, packets: [], running: false, queued: false };state.lanes.set(lane.machine, lane); }
+                append(state, lane, input, receipt);
+            });
+        },
+        abort(error = new Error('Segment batches stopped')) { abort(state, error); },
+        stop() {
+            abort(state, new Error('Segment batches stopped'));
+            return deadline(Promise.allSettled([...state.tasks]), stopTimeoutMs, 'Segment batch stop');
+        }
+    };
+}

package/src/infrastructure/ingest/pipelines/segmentBatchPolicy.js

@@ -0,0 +1,23 @@
+const defaults = { enabled: true, maxMessages: 32, maxBytes: 1048576, maxWaitMs: 100,
+    completedSegments: 1, concurrency: 2, timeoutMs: 10000, statsIntervalMs: 10000 };
+
+function checkLimits(policy) {
+    for (const key of ['maxMessages', 'maxBytes', 'maxWaitMs', 'concurrency', 'timeoutMs', 'completedSegments', 'statsIntervalMs']) {
+        const minimum = ['completedSegments', 'statsIntervalMs'].includes(key) ? 0 : 1;
+        if (!Number.isSafeInteger(policy[key]) || policy[key] < minimum) { throw new TypeError(`${key} must be a bounded integer >= ${minimum}`); }
+    }
+    for (const key of ['maxWaitMs', 'timeoutMs', 'statsIntervalMs']) {
+        if (policy[key] > 2147483647) { throw new TypeError(`${key} exceeds the timer limit`); }
+    }
+}
+
+/** Finite batch limits shared by environment loading and direct collector composition. */
+export default function segmentBatchPolicy(input = {}) {
+    const unknown = Object.keys(input).find(key => { return !Object.hasOwn(defaults, key); });
+    if (unknown) { throw new TypeError(`Unknown segment transaction setting: ${unknown}`); }
+    const policy = { ...defaults, ...input };
+    if (typeof policy.enabled !== 'boolean') { throw new TypeError('enabled must be a boolean'); }
+    if (!policy.enabled) { return { enabled: false }; }
+    checkLimits(policy);
+    return policy;
+}

package/src/infrastructure/ingest/pipelines/segmentPipeline.js

@@ -1,4 +1,7 @@
 import stompOptions from './stompOptions.js';
+import segmentTransactions from './segmentTransactions.js';
+import segmentBatchPolicy from './segmentBatchPolicy.js';
+import stopSegmentPipeline from './stopSegmentPipeline.js';
 import deadline from '../../streams/deadline.js';
 import { postgresSink, stompSource } from '../../streams/index.js';
 import segmentDispatch from '../../../domain/segment/dispatch.js';
@@ -53,7 +56,8 @@ function segmentSinks(postgres, pool) {
  * @returns {object} Pipeline with start() and stop() methods
  */
 export default function segmentPipeline(stomp, postgres, pool, config) {
-    const budget = silenceBudget(config.segmentWindow || 15);
+    const settings = config.transactions?.enabled ? { ...config, transactions: segmentBatchPolicy(config.transactions) } : config;
+    const budget = silenceBudget(settings.segmentWindow || 15);
     const { segmentSink, splitSink } = segmentSinks(postgres, pool);
     const continued = continuedSegments(segmentSink, pool, budget);
     const dispatch = segmentDispatch(continued, retagSink(pool), splitSink, closeOrphanOpen(pool), pool);
@@ -62,21 +66,24 @@ export default function segmentPipeline(stomp, postgres, pool, config) {
     const codec = segmentCodec(dispatch);
     const bounded = { accept(envelope) {
         return deadline(Promise.resolve().then(() => { return codec.accept(envelope); }),
-            config.acceptTimeoutMs ?? 10000, 'STOMP acceptance', (error) => { source.fail(error); });
+            settings.acceptTimeoutMs ?? 10000, 'STOMP acceptance', (error) => { source.fail(error); });
     } };
     // Heartbeat timer flushes outlive source.accept and need their own execution deadline.
-    const coalesce = segmentCoalesce(bounded, {
-        size: config.size,
-        deadLetter: config.deadLetter,
-        interval: config.interval
+    const coalesce = settings.transactions?.enabled ? segmentTransactions(dispatch, pool, settings, error => { source.fail(error); }) : segmentCoalesce(bounded, {
+        size: settings.size,
+        deadLetter: settings.deadLetter,
+        interval: settings.interval
     });
-    const destination = config.segmentsDestination || segmentsIngestDestination;
+    const destination = settings.segmentsDestination || segmentsIngestDestination;
     // Each admitted frame can flush one heartbeat and then persist itself; prefetch bounds queue depth.
-    const deliveryTimeoutMs = Math.min(2147483647, (config.acceptTimeoutMs ?? 10000) * (config.prefetch ?? 32) * 2);
+    const executionMs = settings.transactions?.enabled ? settings.transactions.timeoutMs : settings.acceptTimeoutMs ?? 10000;
+    const deliveryTimeoutMs = Math.min(2147483647, executionMs * (settings.prefetch ?? 32) * 2 + (settings.transactions?.maxWaitMs ?? 0));
     source = stompSource(stomp, destination, coalesce,
-        stompOptions(config, { serial: false, manualAck: true, deliveryTimeoutMs }));
+        stompOptions(settings, { serial: false, manualAck: true, deliveryTimeoutMs, onFatal(error) {
+            coalesce.abort?.(error);settings.onFatal?.(error);
+        } }));
     const silence = silentOpenWatch(closeSilentOpen(pool), budget, {
-        intervalMs: (config.poll || 5) * 1000
+        intervalMs: (settings.poll || 5) * 1000
     });
     return {
         health() { return source.health(); },
@@ -89,10 +96,8 @@ export default function segmentPipeline(stomp, postgres, pool, config) {
             await source.start();
             await silence.start();
         },
-        async stop() {
-            await silence.stop();
-            await source.stop();
-            await pool.end();
+        stop() {
+            return stopSegmentPipeline(source, coalesce, silence, pool, settings.stopTimeoutMs ?? 5000);
         }
     };
 }

package/src/infrastructure/ingest/pipelines/segmentTransactions.js

@@ -0,0 +1,25 @@
+import segmentBatch from './segmentBatch.js';
+import segmentTransaction from '../sinks/segmentTransaction.js';
+import { decodeSegment } from '../codecs/segmentCodec.js';
+
+/** Decode before enqueue; every command and receipt remains ordered until durable commit. */
+export default function segmentTransactions(dispatch, pool, config, onFatal) {
+    const options = config.transactions;
+    const writer = segmentTransaction(pool, dispatch, { timeoutMs: options.timeoutMs, onFatal });
+    const batch = segmentBatch(records => { return writer.write(records); }, {
+        ...options, prefetch: config.prefetch, deadLetter: config.deadLetter,
+        stopTimeoutMs: config.stopTimeoutMs, onFatal, onAbort(error) { writer.abort(error); }, onBatch: config.onBatch
+    });
+    return {
+        accept(envelope) {
+            try {
+                return batch.accept({ record: decodeSegment(envelope), settle: envelope.settle, bytes: Buffer.byteLength(envelope.payload) });
+            } catch (error) {
+                envelope.settle.nack(!(config.deadLetter && error.permanent));
+                return Promise.reject(error);
+            }
+        },
+        abort(error) { batch.abort(error); },
+        stop() { return batch.stop(); }
+    };
+}

package/src/infrastructure/ingest/pipelines/stopSegmentPipeline.js

@@ -0,0 +1,18 @@
+import deadline from '../../streams/deadline.js';
+
+function attempt(action) {
+    try { return Promise.resolve(action()); } catch (error) { return Promise.reject(error); }
+}
+/** Every cleanup runs even if another component throws or cannot drain. */
+export default async function stopSegmentPipeline(source, collector, silence, pool, timeoutMs = 5000) {
+    const end = performance.now() + timeoutMs;
+    const stops = [attempt(() => {return source.stop()}), attempt(() => {return collector.abort?.()}),
+        attempt(() => {return silence.stop()}), attempt(() => {return collector.stop?.()})];
+    try {
+        const results = await deadline(Promise.allSettled(stops), timeoutMs, 'Segment pipeline stop');
+        const failed = results.find(result => {return result.status === 'rejected'});
+        if (failed) { throw failed.reason; }
+    } finally {
+        await deadline(attempt(() => {return pool.end()}), Math.max(1, end - performance.now()), 'Segment pool close');
+    }
+}

package/src/infrastructure/ingest/sinks/retagSink.js

@@ -26,11 +26,11 @@ export default function retagSink(pool) {
          *
          * @param {object} record - Record with machine, start_time, tags, properties
          */
-        async accept({ machine, start_time: startTime, tags, properties, options, resolved }) {
+        async accept({ machine, start_time: startTime, tags, properties, options, resolved }, transaction) {
             try {
                 const opts = options === undefined || options === null ? null : options;
                 const flag = typeof resolved === 'boolean' ? resolved : true;
-                await pool.query(
+                await (transaction || pool).query(
                     'UPDATE segments SET tags = $1, properties = $2, options = $3, resolved = $4 WHERE machine = $5 AND start_time = $6',
                     [tags, properties, opts, flag, machine, startTime]
                 );

package/src/infrastructure/ingest/sinks/segmentTransaction.js

@@ -0,0 +1,76 @@
+import deadline from '../../streams/deadline.js';
+
+function release(token, destroy = false) {
+    if (token.client && !token.released) {
+        token.released = true;
+        if (token.onError) { token.client.removeListener?.('error', token.onError); }
+        token.client.release(destroy);
+    }
+}
+function permanent(error) {
+    return error.permanent === true || error instanceof RangeError || /^(?:22|23)/u.test(error.code ?? '');
+}
+async function prepare(pool, state, token) {
+    token.client = await pool.connect();
+    if (token.cancelled || state.stopped) { throw state.failure ?? new Error('Segment transaction stopped'); }
+    token.onError = error => { state.fail(error); };
+    token.client.on?.('error', token.onError);
+    await token.runner.query('BEGIN');
+    await token.runner.query("SELECT set_config('statement_timeout', $1, true)", [String(state.timeoutMs)]);
+}
+async function rollback(token) {
+    if (!token.client || token.cancelled) { return false; }
+    try { await token.runner.query('ROLLBACK');return true; }
+    catch {
+        // Unknown transaction outcome: the owner fences and destroys the connection.
+        return false;
+    }
+}
+async function apply(dispatch, records, token) {
+    for (const record of records) {
+        // eslint-disable-next-line no-await-in-loop
+        await dispatch.accept(record, token.runner);
+    }
+}
+async function execute(pool, dispatch, records, state, token) {
+    let phase = 'prepare';
+    try {
+        await prepare(pool, state, token);
+        phase = 'apply';await apply(dispatch, records, token);
+        phase = 'commit';await token.runner.query('COMMIT');
+        return { sqlCalls: token.calls };
+    } catch (error) {
+        const confirmed = await rollback(token);
+        if (confirmed && phase !== 'prepare' && permanent(error)) { error.permanent = true; }
+        else if (!state.stopped && !token.cancelled) { state.fail(error); }
+        throw error;
+    } finally {
+        state.active.delete(token);
+        release(token, token.cancelled || state.stopped);
+    }
+}
+
+/** Owns one durable transaction per batch, including late-connect and timeout fencing. */
+export default function segmentTransaction(pool, dispatch, { timeoutMs = 10000, onFatal } = {}) {
+    const state = { stopped: false, failure: null, active: new Set(), timeoutMs,
+        fail(error) {
+            if (state.failure || state.stopped) { return; }
+            state.failure = error;onFatal?.(error);
+        } };
+    return {
+        write(records) {
+            if (state.stopped || state.failure) { return Promise.reject(state.failure ?? new Error('Segment transaction stopped')); }
+            const token = { client: null, released: false, cancelled: false, calls: 0 };
+            token.runner = { query(...args) { token.calls += 1;return token.client.query(...args); } };
+            state.active.add(token);
+            return deadline(execute(pool, dispatch, records, state, token), timeoutMs, 'Segment transaction', error => {
+                token.cancelled = true;
+                try { release(token, true); } finally { state.fail(error); }
+            });
+        },
+        abort(error = new Error('Segment transaction stopped')) {
+            state.stopped = true;state.failure ??= error;
+            for (const token of state.active) { token.cancelled = true;release(token, true); }
+        }
+    };
+}

package/src/infrastructure/ingest/telemetry/amqpMetricsIngest.js

@@ -56,7 +56,10 @@ export function telemetryConsumer(codec, channel, onSeen) {
  */
 export default function amqpMetricsIngest(amqpUrl, queue, sink, options = {}) {
     const prefetch = options.prefetch || 32;
-    const collector = ingestBatch(sink, options);
+    // Unacknowledged deliveries occupy the broker window until the batch commits.
+    // A larger batch can never fill and would throttle ingestion to the flush timer.
+    const size = Math.min(options.size ?? 100, prefetch);
+    const collector = ingestBatch(sink, { ...options, size });
     const codec = metricsCodec(collector);
     const session = amqpSource(amqpUrl, queue, {
         accept(delivery) {

package/src/infrastructure/streams/stompSource.js

@@ -92,9 +92,7 @@ async function deliver(ctx, body) {
       settle.ack();
     }
   } catch (error) {
-    if (!ctx.manualAck) {
-      settle.nack();
-    }
+    settle.nack();
     throw error;
   }
 }