@yarkivaev/scada 2.3.116 → 2.4.0

package/src/application/runtime/resourceClaims.js

@@ -0,0 +1,21 @@
+/** Exclusive resource claims remain held when cleanup cannot be proved. */
+export default function resourceClaims() {
+    const claims = new Map();
+    return {
+        check(taskId, resources) {
+            if (!Array.isArray(resources) || resources.some((key) => { return typeof key !== 'string' || !key; })) {
+                throw new TypeError('Invalid task resources');
+            }
+            resources.forEach((key) => {
+                if (claims.has(key) && claims.get(key) !== taskId) { throw new Error(`Resource already claimed: ${key}`); }
+            });
+        },
+        acquire(taskId, resources) {
+            this.check(taskId, resources);
+            resources.forEach((key) => { claims.set(key, taskId); });
+        },
+        release(taskId) {
+            claims.forEach((owner, key) => { if (owner === taskId) { claims.delete(key); } });
+        }
+    };
+}

package/src/application/runtime/runCollector.js

@@ -0,0 +1,50 @@
+import { readManifest, validateManifest } from './manifest.js';
+import collectorSignals from './collectorSignals.js';
+import createRuntime from './runtime.js';
+import runtimeServices from './runtimeServices.js';
+import runtimeHealth from './runtimeHealth.js';
+
+async function apply(runtime, document) {
+    for (const removal of document.removals ?? []) {
+        // Retire explicitly before opening replacement resource owners.
+        // eslint-disable-next-line no-await-in-loop
+        await runtime.remove(removal);
+    }
+    for (const input of document.assignments) {
+        // Keep startup concurrency bounded; task execution remains concurrent.
+        // eslint-disable-next-line no-await-in-loop
+        await runtime.apply(input);
+    }
+}
+/** Local executable host. The external agent can instead use createRuntime directly. */
+export default async function runCollector({ registry, env = process.env, argv = process.argv.slice(2), signals = true, manifestReader = readManifest, ...services }) {
+    const owned = runtimeServices(env, services);
+    const runtime = createRuntime({ registry, ...owned });
+    const state = { health: null, reloading: false, stopped: false, detach: null };
+    const collector = {
+        runtime,
+        async reload() {
+            if (state.stopped || state.reloading) { throw new Error('Collector stopped or reload in progress'); }
+            state.reloading = true;
+            try {
+                const document = await manifestReader(env, argv, runtime.status());
+                await validateManifest(document, registry);
+                await apply(runtime, document);
+            } finally { Object.assign(state, { reloading: false }); }
+        },
+        async stop() {
+            state.stopped = true;
+            state.detach?.();
+            try { await runtime.stop(); } finally { await Promise.all([owned.close(), state.health?.stop()]); }
+        }
+    };
+    if (signals) { state.detach = collectorSignals(collector); }
+    try {
+        await collector.reload();
+        if (env.COLLECTOR_HEALTH_PORT) { state.health = await runtimeHealth(runtime, { port: Number(env.COLLECTOR_HEALTH_PORT), host: env.COLLECTOR_HEALTH_HOST ?? '127.0.0.1' }); }
+    } catch (error) {
+        try { await collector.stop(); } catch (cleanup) { throw new AggregateError([error, cleanup], 'Collector startup cleanup failed'); }
+        throw error;
+    }
+    return collector;
+}

package/src/application/runtime/runtime.js

@@ -0,0 +1,86 @@
+import assignment, { identity } from './assignment.js';
+import { halt, launch, view } from './taskSlot.js';
+import resourceClaims from './resourceClaims.js';
+import deadline from './deadline.js';
+import taskBudget from './taskBudget.js';
+
+function positive(value) {
+    if (!Number.isSafeInteger(value) || value <= 0) { throw new TypeError('Runtime limits must be positive integers'); }
+    return value;
+}
+function slotFor(ctx, taskId) {
+    if (!ctx.slots.has(taskId)) {
+        if (ctx.slots.size >= ctx.maxTasks) { throw new Error('Task capacity exceeded'); }
+        ctx.slots.set(taskId, { taskId, generation: -1, state: 'idle', removed: false, task: null, chain: Promise.resolve() });
+    }
+    return ctx.slots.get(taskId);
+}
+function enqueue(ctx, input, action) {
+    try {
+        identity(input);
+        if (ctx.stopping || ctx.fatal) { throw new Error('Runtime stopping or fatal'); }
+        if (ctx.pending >= ctx.maxPending) { throw new Error('Control capacity exceeded'); }
+        const slot = slotFor(ctx, input.taskId);
+        ctx.pending += 1;
+        const result = slot.chain.then(() => { return action(slot); }).finally(() => { ctx.pending -= 1; });
+        slot.chain = result.catch(() => {
+            // Preserve sequencing after a rejected command.
+        });
+        return result;
+    } catch (error) { return Promise.reject(error); }
+}
+function duplicate(slot, request) {
+    if (request.generation < slot.generation || (request.generation === slot.generation && slot.removed)) {
+        throw new Error('stale assignment');
+    }
+    if (request.generation !== slot.generation) { return false; }
+    if (slot.specHash !== request.specHash) { throw new Error('assignment conflict'); }
+    return true;
+}
+async function apply(ctx, input, slot) {
+    if (ctx.fatal || ctx.stopping) { throw new Error('Runtime stopping or fatal'); }
+    const request = assignment(input, ctx.registry);
+    if (duplicate(slot, request)) { return view(slot); }
+    await deadline(() => { return request.adapter.validate(request.spec); }, ctx.startTimeoutMs);
+    if (ctx.fatal || ctx.stopping) { throw new Error('Runtime stopping or fatal'); }
+    const resources = request.adapter.resources(request.spec);
+    ctx.claims.check(slot.taskId, resources);
+    await halt(slot, ctx);
+    if (ctx.fatal || ctx.stopping) { throw new Error('Runtime stopping or fatal'); }
+    await launch(slot, request, ctx, resources);
+    return view(slot);
+}
+async function remove(ctx, input, slot) {
+    if (input.generation < slot.generation) { return view(slot); }
+    slot.generation = input.generation;
+    slot.removed = true;
+    await halt(slot, ctx);
+    Object.assign(slot, { state: 'stopped' });
+    return view(slot);
+}
+function shutdown(ctx, milliseconds) {
+    ctx.stopping = true;
+    ctx.slots.forEach((slot) => { slot.controller?.abort(new Error('Runtime stopping')); });
+    const tasks = Array.from(ctx.slots.values()).map((slot) => {
+        return slot.chain.then(() => { return halt(slot, ctx); });
+    });
+    return deadline(() => { return Promise.all(tasks); }, milliseconds).catch((error) => {
+        ctx.fatal = true;
+        throw error;
+    });
+}
+/** Identical local executors; placement and distributed ownership belong outside. */
+export default function createRuntime(options) {
+    const ctx = { registry: options.registry, slots: new Map(), claims: resourceClaims(), pending: 0, stopping: false, fatal: false,
+        maxTasks: positive(options.maxTasks ?? 1000), maxPending: positive(options.maxPending ?? 100),
+        stopTimeoutMs: positive(options.stopTimeoutMs ?? 10000), startTimeoutMs: positive(options.startTimeoutMs ?? 10000),
+        budget: taskBudget(options.budgets ?? { maxBytes: 16777216, maxRecords: 16384 }),
+        services: { stateStore: options.stateStore, secrets: options.secrets, report: options.report } };
+    if (!(ctx.registry instanceof Map)) { throw new TypeError('registry must be a Map'); }
+    return {
+        apply(input) { return enqueue(ctx, input, (slot) => { return apply(ctx, input, slot); }); },
+        remove(input) { return enqueue(ctx, input, (slot) => { return remove(ctx, input, slot); }); },
+        status() { return { fatal: ctx.fatal, stopping: ctx.stopping, budget: ctx.budget.status(), tasks: Array.from(ctx.slots.values()).map(view) }; },
+        stop({ deadlineMs = ctx.stopTimeoutMs } = {}) { return shutdown(ctx, positive(deadlineMs)); }
+    };
+}

package/src/application/runtime/runtimeHealth.js

@@ -0,0 +1,29 @@
+import { createServer } from 'node:http';
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+
+function response(runtime, histogram, request, result) {
+    if (!['/live', '/ready', '/status'].includes(request.url)) { result.writeHead(404).end(); return; }
+    const state = runtime.status();
+    const ready = !state.fatal && !state.stopping;
+    const body = request.url === '/status' ? { ...state, memory: process.memoryUsage(), eventLoopP99Ms: histogram.percentile(99) / 1e6 } : { ready };
+    result.writeHead((request.url === '/ready' && !ready) || (request.url === '/live' && state.fatal) ? 503 : 200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+    result.end(JSON.stringify(body));
+}
+/** Read-only health surface. A blocked event loop cannot answer an external probe. */
+export default async function runtimeHealth(runtime, { port, host = '127.0.0.1' }) {
+    if (!Number.isInteger(port) || port < 0 || port > 65535) { throw new TypeError('Invalid health port'); }
+    const histogram = monitorEventLoopDelay({ resolution: 20 });
+    const server = createServer((request, result) => { response(runtime, histogram, request, result); });
+    server.requestTimeout = 2000;
+    server.headersTimeout = 2000;
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, host, resolve); });
+    histogram.enable();
+    return {
+        port: server.address().port,
+        stop() {
+            histogram.disable();
+            server.closeAllConnections();
+            return new Promise((resolve, reject) => { server.close((error) => { if (error) { reject(error); } else { resolve(); } }); });
+        }
+    };
+}

package/src/application/runtime/runtimeServices.js

@@ -0,0 +1,15 @@
+import pg from 'pg';
+import taskStatePg from '../../infrastructure/persistence/runtime/taskStatePg.js';
+import deadline from './deadline.js';
+
+/** Storage is optional for live-only tasks and mandatory for durable adapters. */
+export default function runtimeServices(env, supplied) {
+    const pool = !supplied.stateStore && env.COLLECTOR_STATE_URL ? new pg.Pool({
+        connectionString: env.COLLECTOR_STATE_URL, max: 4, connectionTimeoutMillis: 5000,
+        query_timeout: 10000, statement_timeout: 10000, idleTimeoutMillis: 30000
+    }) : null;
+    return { ...supplied, secrets: supplied.secrets ?? { get(name) { return env[name]; } },
+        stateStore: supplied.stateStore ?? (pool ? taskStatePg(pool) : undefined),
+        close() { return pool ? deadline(() => { return pool.end(); }, 10000) : Promise.resolve(); }
+    };
+}

package/src/application/runtime/stateDocument.js

@@ -0,0 +1,22 @@
+function validate(value, seen, depth) {
+    if (depth > 128) { throw new TypeError('Task state JSON is too deeply nested'); }
+    if (value === null || typeof value !== 'object') { return; }
+    if (seen.has(value)) { throw new TypeError('Task state JSON must not contain cycles'); }
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+        throw new TypeError('Task state requires JSON data; encode binary as a string explicitly');
+    }
+    if (!(Array.isArray(value) || value instanceof Date || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+        throw new TypeError('Task state requires plain JSON data');
+    }
+    seen.add(value);
+    Object.values(value).forEach((item) => { validate(item, seen, depth + 1); });
+    seen.delete(value);
+}
+/** Normalize before first delivery so recovered PostgreSQL JSON has identical types. */
+export default function stateDocument(value, maxBytes) {
+    validate(value, new Set(), 0);
+    const text = JSON.stringify(value);
+    if (typeof text !== 'string') { throw new TypeError('Task state requires JSON data'); }
+    if (Buffer.byteLength(text) > maxBytes) { throw new Error('Task state capacity exceeded'); }
+    return JSON.parse(text);
+}

package/src/application/runtime/streamPorts.js

@@ -0,0 +1,42 @@
+import { clock, intervalSource } from '@yarkivaev/source-to-sink';
+import { amqpSink, amqpSource, clickhouseSink, lokiSource, modbusRtuSource, modbusSource, mqttSink, mqttSource, postgresSink, serialSource } from '../../infrastructure/streams/index.js';
+import opcuaSource from '../../infrastructure/opcua/source.js';
+import resolveSecrets from './resolveSecrets.js';
+
+// Protocol buffers charge bytes; stream acceptance owns the logical record slot.
+function bytesOnly(budget) {
+    return { reserve({ bytes }) { return budget.reserve({ bytes, records: 0 }); } };
+}
+function configured(factory) {
+    return (spec, collector, context) => { return factory(resolveSecrets(spec, context.secrets), collector, context); };
+}
+export function sources() {
+    return new Map([
+        ['opcua', configured((spec, collector, ctx) => { return opcuaSource(spec.connections, collector, { ...spec.options, budget: bytesOnly(ctx.budget), onError() { ctx.report?.({ state: 'degraded' }); } }); })],
+        ['serial', configured((spec, collector, ctx) => { return serialSource(spec.devices, collector, { ...spec.options, budget: bytesOnly(ctx.budget), onError() { ctx.report?.({ state: 'degraded' }); } }); })],
+        ['amqp', configured((spec, collector, ctx) => { return amqpSource(spec.url, spec.queue, collector, { ...spec.options, budget: bytesOnly(ctx.budget) }); })],
+        ['mqtt', configured((spec, collector, ctx) => { return mqttSource(spec.url, spec.topics, collector, { ...spec.options, budget: bytesOnly(ctx.budget) }); })],
+        ['interval', configured((spec, collector) => { return intervalSource(spec.intervalMs, collector, spec.options); })],
+        ['loki', configured((spec, collector) => { return lokiSource(spec.url, spec.query, spec.interval, collector, clock(), spec.options); })],
+        ['modbus-tcp', configured((spec, collector) => { return modbusSource(spec.host, spec.port, spec.address, spec.count, spec.interval, collector, clock()); })],
+        ['modbus-rtu', configured((spec, collector) => { return modbusRtuSource(spec.path, spec.serial, spec.address, spec.count, spec.interval, collector, clock()); })]
+    ]);
+}
+export function sinks() {
+    const factories = new Map([
+        ['amqp', (spec) => { return amqpSink(spec.url, spec.options); }],
+        ['mqtt', (spec) => { return mqttSink(spec.url, spec.options); }],
+        ['clickhouse', (spec) => { return clickhouseSink(spec.url, spec.table); }],
+        ['postgres', (spec) => { return postgresSink(spec.url, spec.table, spec.columns); }]
+    ]);
+    return new Map(Array.from(factories, ([name, factory]) => {
+        return [name, (spec, context) => { return factory(resolveSecrets(spec, context.secrets)); }];
+    }));
+}
+export function resources(spec) {
+    const {source} = spec;
+    if (source.type === 'serial') { return [...new Set(source.devices.map((device) => { return `serial:${device.path}`; }))]; }
+    if (source.type === 'modbus-rtu') { return [`serial:${source.path}`]; }
+    if (source.type === 'opcua') { return source.connections.map((connection) => { return `opcua:${connection.url}`; }); }
+    return [];
+}

package/src/application/runtime/streamTask.js

@@ -0,0 +1,105 @@
+import taskState from './taskState.js';
+import deadline from './deadline.js';
+import budgetedSink from './budgetedSink.js';
+
+function validate(spec, ports) {
+    if (!ports.sources.has(spec.source?.type)) { throw new TypeError('Unknown stream source'); }
+    if (!Array.isArray(spec.sinks) || !spec.sinks.length || spec.sinks.some((sink) => { return !ports.sinks.has(sink.type); })) {
+        throw new TypeError('Unknown stream sink');
+    }
+    if (!['live', 'durable'].includes(spec.delivery)) { throw new TypeError('Explicit delivery policy required'); }
+    const names = spec.sinks.map((sink, index) => { return sink.id ?? String(index); });
+    if (new Set(names).size !== names.length) { throw new TypeError('Duplicate sink id'); }
+    if (spec.delivery === 'durable' && spec.sinks.some((sink) => { return sink.type === 'mqtt' && ![1, 2].includes(sink.options?.qos); })) {
+        throw new TypeError('Durable MQTT delivery requires QoS 1 or 2');
+    }
+    if (spec.transform && !ports.transforms.has(spec.transform)) { throw new TypeError('Unknown stream transform'); }
+    if (spec.delivery === 'durable' && (!spec.stateVersion || !spec.compatibilityKey)) {
+        throw new TypeError('Durable stream requires stateVersion and compatibilityKey');
+    }
+}
+async function durable(bag, value) {
+    const {pending} = bag.state.snapshot();
+    if (pending?.event.eventId === value.eventId && JSON.stringify(pending.event) !== JSON.stringify(value)) {
+        throw new Error('Conflicting event identity');
+    }
+    await bag.state.resume(bag.sinks);
+    if (pending?.event.eventId !== value.eventId) { await bag.state.deliver(value, bag.sinks, value.checkpoint ?? null); }
+}
+async function accept(bag, record) {
+    bag.context.signal.throwIfAborted();
+    if (bag.stopped) { throw new Error('Stream stopped'); }
+    const release = bag.context.budget.reserve({ bytes: Buffer.byteLength(JSON.stringify(record)), records: 1 });
+    try {
+        const value = bag.transform ? await bag.transform(record) : record;
+        bag.context.signal.throwIfAborted();
+        if (value === null) { return; }
+        if (bag.state) { await durable(bag, value); }
+        else {
+            await Promise.all(Object.values(bag.sinks).map((sink) => {
+                bag.context.signal.throwIfAborted();
+                return deadline(() => { return sink.write([value], { signal: bag.context.signal }); }, bag.timeoutMs);
+            }));
+        }
+        bag.context.report?.({ state: 'running', delivered: 1 });
+    } finally { release(); }
+}
+function current(bag) {
+    bag.context.signal.throwIfAborted();
+    if (bag.stopped) { throw new Error('Stream stopped'); }
+}
+async function restore(bag) {
+    if (!bag.state) { return; }
+    const {checkpoint} = bag.state.snapshot();
+    if (checkpoint !== null && typeof bag.source.restore !== 'function') { throw new Error('Durable source cannot restore its checkpoint'); }
+    if (typeof bag.source.restore === 'function') { await bag.source.restore(checkpoint); }
+}
+async function start(bag) {
+    if (bag.state) { await bag.state.open(); }
+    current(bag);
+    await Promise.all(Object.values(bag.sinks).map((sink) => { return sink.start?.(); }));
+    current(bag);
+    if (bag.state) { await bag.state.resume(bag.sinks); }
+    current(bag);
+    await restore(bag);
+    current(bag);
+    await bag.source.start();
+}
+async function stop(bag) {
+    bag.stopped = true;
+    // A failed source cleanup must not be mistaken for a completed release.
+    try { await bag.source.stop(); } finally {
+        await Promise.all(Object.values(bag.sinks).map((sink) => { return sink.stop?.(); }));
+    }
+}
+function recipient(spec, stream, context, ports) {
+    const sink = ports.sinks.get(spec.type)(spec, context);
+    if (stream.delivery !== 'durable' || spec.type !== 'amqp') { return sink; }
+    return {
+        start() { return sink.start?.(); },
+        stop() { return sink.stop?.(); },
+        write(records, options) {
+            return sink.write(records.map((record) => { return { ...record,
+                options: { ...record.options, persistent: true, mandatory: true, messageId: record.eventId } }; }), options);
+        }
+    };
+}
+function create(spec, context, ports) {
+    if (spec.delivery === 'durable' && !context.stateStore) { throw new TypeError('Durable stateStore required'); }
+    const sinks = Object.fromEntries(spec.sinks.map((sink, index) => {
+        return [sink.id ?? String(index), budgetedSink(recipient(sink, spec, context, ports), context.budget, false)];
+    }));
+    const bag = { sinks, context, stopped: false, timeoutMs: spec.writeTimeoutMs ?? 10000,
+        transform: ports.transforms.get(spec.transform),
+        state: spec.delivery === 'durable' ? taskState(context.stateStore, { ...spec, taskId: context.taskId, signal: context.signal }) : null };
+    bag.source = ports.sources.get(spec.source.type)(spec.source, { accept(record) { return accept(bag, record); } }, context);
+    return { start() { return start(bag); }, stop() { return stop(bag); } };
+}
+/** One lifecycle for arbitrary registered source/transform/sink combinations. */
+export default function streamTask(ports) {
+    return {
+        validate(spec) { validate(spec, ports); },
+        resources(spec) { return spec.resources ?? []; },
+        create(spec, context) { return create(spec, context, ports); }
+    };
+}

package/src/application/runtime/taskBudget.js

@@ -0,0 +1,31 @@
+function validate(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) { throw new TypeError(`Invalid ${name}`); }
+}
+/** No waiting queue: callers choose backpressure, durable spooling or explicit loss. */
+export default function taskBudget(limits, parent) {
+    validate(limits.maxBytes, 'maxBytes');
+    validate(limits.maxRecords, 'maxRecords');
+    const usage = { bytes: 0, records: 0 };
+    return {
+        reserve({ bytes, records }) {
+            validate(bytes, 'reservation');
+            validate(records, 'reservation');
+            if (usage.bytes + bytes > limits.maxBytes || usage.records + records > limits.maxRecords) {
+                throw new Error('Task capacity exceeded');
+            }
+            const releaseParent = parent?.reserve({ bytes, records });
+            usage.bytes += bytes;
+            usage.records += records;
+            let released = false;
+            return () => {
+                if (!released) {
+                    released = true;
+                    usage.bytes -= bytes;
+                    usage.records -= records;
+                    releaseParent?.();
+                }
+            };
+        },
+        status() { return { ...usage }; }
+    };
+}

package/src/application/runtime/taskContext.js

@@ -0,0 +1,18 @@
+import taskBudget from './taskBudget.js';
+
+/** Context never mutates environment or installs process-global handlers. */
+export default function taskContext(slot, request, ctx) {
+    const budget = taskBudget({ maxBytes: request.spec.limits?.maxBytes ?? 1048576,
+        maxRecords: request.spec.limits?.maxRecords ?? 1024 }, ctx.budget);
+    const { controller } = slot;
+    return { ...ctx.services, taskId: slot.taskId, generation: slot.generation, signal: controller.signal, budget,
+        report(event) {
+            if (controller.signal.aborted) { return; }
+            slot.health = event.state;
+            if (event.delivered) { slot.lastDelivery = Date.now(); }
+            try { ctx.services.report?.({ taskId: slot.taskId, generation: slot.generation, ...event }); } catch {
+                // Observability cannot interrupt collection.
+            }
+        }
+    };
+}

package/src/application/runtime/taskQueue.js

@@ -0,0 +1,21 @@
+/** Serial execution with admission bounded before adding anything to the chain. */
+export default function taskQueue({ budget, signal }) {
+    let pending = Promise.resolve();
+    return {
+        run(operation, { bytes = 0, records = 1 } = {}) {
+            try {
+                signal.throwIfAborted();
+                const release = budget.reserve({ bytes, records });
+                const result = pending.then(() => {
+                    signal.throwIfAborted();
+                    return operation();
+                }).finally(release);
+                pending = result.catch(() => {
+                    // Rejection belongs to this operation, not the next queued one.
+                });
+                return result;
+            } catch (error) { return Promise.reject(error); }
+        },
+        drain() { return pending; }
+    };
+}

package/src/application/runtime/taskSlot.js

@@ -0,0 +1,46 @@
+import deadline from './deadline.js';
+import taskContext from './taskContext.js';
+
+export async function halt(slot, ctx) {
+    if (!slot.task) { return; }
+    slot.state = 'stopping';
+    slot.controller.abort(new Error('Task revoked'));
+    try {
+        await deadline(() => { return slot.task.stop({ signal: slot.controller.signal }); }, ctx.stopTimeoutMs);
+        ctx.claims.release(slot.taskId);
+        slot.task = null;
+        slot.state = 'stopped';
+    } catch (error) {
+        slot.state = 'failed';
+        ctx.fatal = true;
+        slot.reason = error.code ?? error.name;
+        throw error;
+    }
+}
+function validateTask(task) {
+    if (!task || typeof task.start !== 'function' || typeof task.stop !== 'function') {
+        throw new TypeError('Adapter must return synchronous lifecycle object');
+    }
+}
+export async function launch(slot, request, ctx, resources) {
+    ctx.claims.acquire(slot.taskId, resources);
+    Object.assign(slot, { generation: request.generation, specHash: request.specHash, removed: false, state: 'starting', reason: null });
+    slot.controller = new AbortController();
+    const context = taskContext(slot, request, ctx);
+    try {
+        // Factories are synchronous: all I/O belongs in cancellable start().
+        slot.task = request.adapter.create(request.spec, context);
+        validateTask(slot.task);
+        await deadline(() => { return slot.task.start(); }, ctx.startTimeoutMs);
+        Object.assign(slot, { state: 'running' });
+    } catch (error) {
+        if (slot.task && typeof slot.task.stop === 'function') { await halt(slot, ctx); }
+        else { ctx.claims.release(slot.taskId); slot.task = null; }
+        Object.assign(slot, { state: 'failed', reason: error.code ?? error.name });
+        throw error;
+    }
+}
+export function view(slot) {
+    return { taskId: slot.taskId, generation: slot.generation, specHash: slot.specHash,
+        state: slot.state, health: slot.health ?? 'unknown', lastDelivery: slot.lastDelivery ?? null, reason: slot.reason ?? null };
+}

package/src/application/runtime/taskState.js

@@ -0,0 +1,73 @@
+import deadline from './deadline.js';
+import stateDocument from './stateDocument.js';
+
+async function save(ctx, changes) {
+    if (ctx.failed) { throw new Error('Task state requires reload'); }
+    ctx.options.signal?.throwIfAborted();
+    const next = { ...ctx.data, ...changes };
+    try {
+        const version = await ctx.store.commit({ ...next, expectedVersion: ctx.data.version, ownership: ctx.options.ownership });
+        ctx.options.signal?.throwIfAborted();
+        Object.assign(ctx, { data: { ...next, version } });
+    } catch (error) { Object.assign(ctx, { failed: true }); throw error; }
+}
+async function resume(ctx, sinks) {
+    if (ctx.failed) { throw new Error('Task state requires reload'); }
+    if (!ctx.data) { throw new Error('Task state must be opened'); }
+    if (!ctx.data.pending) { return; }
+    const { event, remaining, checkpoint } = ctx.data.pending;
+    for (const name of remaining) {
+        ctx.options.signal?.throwIfAborted();
+        if (!sinks[name]) { throw new Error('Missing required sink'); }
+        // Sequential fan-out persists every durable acknowledgement before continuing.
+        // eslint-disable-next-line no-await-in-loop
+        await deadline(() => { return sinks[name].write([event], { signal: ctx.options.signal }); }, ctx.options.writeTimeoutMs ?? 10000);
+        const pending = { event, checkpoint, remaining: ctx.data.pending.remaining.filter((item) => { return item !== name; }) };
+        // eslint-disable-next-line no-await-in-loop
+        await save(ctx, { pending });
+    }
+    await save(ctx, { checkpoint, pending: null });
+}
+function exclusive(ctx, action) {
+    if (ctx.busy) { return Promise.reject(new Error('Task state operation in progress')); }
+    ctx.busy = true;
+    return Promise.resolve().then(action).finally(() => { ctx.busy = false; });
+}
+async function open(ctx) {
+    const saved = await ctx.store.load(ctx.options.taskId);
+    if (saved && (saved.stateVersion !== ctx.options.stateVersion || saved.compatibilityKey !== ctx.options.compatibilityKey)) {
+        throw new Error('Recovered task state is incompatible');
+    }
+    ctx.options.signal?.throwIfAborted();
+    Object.assign(ctx, { data: saved ?? { taskId: ctx.options.taskId, version: 0, stateVersion: ctx.options.stateVersion,
+        compatibilityKey: ctx.options.compatibilityKey, checkpoint: null, pending: null } });
+    Object.assign(ctx, { failed: false });
+}
+async function deliver(ctx, event, sinks, checkpoint) {
+    if (ctx.failed) { throw new Error('Task state requires reload'); }
+    if (!ctx.data) { throw new Error('Task state must be opened'); }
+    if (ctx.data.pending) { throw new Error('Pending delivery must be resumed first'); }
+    if (typeof event.eventId !== 'string' || !event.eventId || Object.keys(sinks).length === 0) {
+        throw new TypeError('Stable eventId and required sinks are mandatory');
+    }
+    const pending = stateDocument({ event, remaining: Object.keys(sinks), checkpoint }, ctx.options.maxBytes ?? 1048576);
+    await save(ctx, { pending });
+    await resume(ctx, sinks);
+}
+/** Durable per-recipient outbox. CAS detects conflicts; it is not distributed fencing. */
+export default function taskState(store, options) {
+    const ctx = { store, options, data: null, busy: false, failed: false };
+    return {
+        open() { return exclusive(ctx, () => { return open(ctx); }); },
+        deliver(event, sinks, checkpoint) { return exclusive(ctx, () => { return deliver(ctx, event, sinks, checkpoint); }); },
+        resume(sinks) { return exclusive(ctx, () => { return resume(ctx, sinks); }); },
+        checkpoint(value) {
+            return exclusive(ctx, () => {
+                if (!ctx.data) { throw new Error('Task state must be opened'); }
+                if (ctx.data.pending) { throw new Error('Pending delivery must be resumed first'); }
+                return save(ctx, { checkpoint: stateDocument(value, options.maxBytes ?? 1048576) });
+            });
+        },
+        snapshot() { return structuredClone(ctx.data); }
+    };
+}

package/src/application/siteCollection.js

@@ -0,0 +1,14 @@
+function external(config) {
+    const mode = config.collectorMode ?? config.env?.COLLECTOR_MODE ?? process.env.COLLECTOR_MODE ?? 'embedded';
+    if (!['embedded', 'external'].includes(mode)) { throw new TypeError('Invalid collectorMode'); }
+    return mode === 'external';
+}
+/** Keep site HTTP/state services while moving autonomous ingestion to executors. */
+export function collectionEnvironment(config) {
+    const env = config.env ?? process.env;
+    return external(config) ? { ...env, SINK_PIPELINES: 'false' } : env;
+}
+export function startCollection(config, start) {
+    if (external(config)) { return undefined; }
+    return start();
+}

package/src/application/siteServer.js

@@ -1,4 +1,4 @@
-import { clickhouseSink } from '@yarkivaev/source-to-sink';
+import { clickhouseSink } from '../infrastructure/streams/index.js';
 import supervisorSink from './supervisorSink.js';
 import plantServer from './plantServer.js';
 import plantOperations from './plantOperations.js';
@@ -11,6 +11,7 @@ import startTelemetryIngest from './siteTelemetry.js';
 import timelineOperatorFromEnv from './timelineOperatorFromEnv.js';
 import { buildSiteOperatorCatalog } from './siteOperatorCatalog.js';
 import siteSyncBind from './sync/siteSyncBind.js';
+import { collectionEnvironment, startCollection } from './siteCollection.js';
 
 function stompFromEnv(env) {
     return {
@@ -118,7 +119,7 @@ function siteExtraRoutes(catalog, extraRoutes, syncRoutes) {
  *   await siteServer({ plantFactory: ({ alerts, userDecisions }, sink) => edgePlant(machines, { metrics: sink.dataAccess.metrics, alerts, userDecisions }), kindSources: { temp } });
  */
 export default async function siteServer(config) {
-    const env = config.env || process.env;
+    const env = collectionEnvironment(config);
     const sink = supervisorSink(env);
     const ops = bindSiteOperations(sink, config.kindSources || config.operationSources);
     const http = edgeApi(sink.dataAccess, {
@@ -132,15 +133,15 @@ export default async function siteServer(config) {
         runRetention
     });
     await sink.run(http);
-    const mqtt = startMqtt(sink, env);
-    const telemetry = startTelemetryIngest(
+    const mqtt = startCollection(config, () => { return startMqtt(sink, env); });
+    const telemetry = startCollection(config, () => { return startTelemetryIngest(
         env,
         config.streams,
         mqttConfigFromEnv(env),
         sink.pool,
         config.intervalDevices
-    );
-    const operationSync = startOperationSync(sink, env);
+    ); });
+    const operationSync = startCollection(config, () => { return startOperationSync(sink, env); });
     const basePath = config.basePath || '/api/v1';
     const catalog = buildSiteOperatorCatalog(config, basePath, sink, env);
     if (catalog.sync) {

package/src/application/siteTelemetry.js

@@ -1,4 +1,4 @@
-import { clickhouseSink } from '@yarkivaev/source-to-sink';
+import { clickhouseSink } from '../infrastructure/streams/index.js';
 import amqpMetricsIngest from '../infrastructure/ingest/telemetry/amqpMetricsIngest.js';
 import foldedMetricsSink from './foldedMetricsSink.js';
 import bindSilentStreams from './bindSilentStreams.js';