@yarkivaev/scada 2.3.115 → 2.4.0

package/src/application/runtime/manifest.js

@@ -0,0 +1,38 @@
+import { createReadStream } from 'node:fs';
+import assignment, { identity } from './assignment.js';
+
+async function read(stream) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of stream) {
+        bytes += Buffer.byteLength(chunk);
+        if (bytes > 1048576) { throw new Error('Manifest capacity exceeded'); }
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export async function readManifest(env, argv) {
+    const text = env.COLLECTOR_MANIFEST ?? await read(argv[0] === '-' ? process.stdin : createReadStream(argv[0] ?? env.COLLECTOR_MANIFEST_PATH));
+    if (Buffer.byteLength(text) > 1048576) { throw new Error('Manifest capacity exceeded'); }
+    return JSON.parse(text);
+}
+export async function validateManifest(document, registry) {
+    if (!document || !Array.isArray(document.assignments) || !Array.isArray(document.removals ?? [])) {
+        throw new TypeError('Manifest requires assignments and optional removals arrays');
+    }
+    const ids = new Set();
+    const resources = new Set();
+    for (const input of [...document.assignments, ...(document.removals ?? [])]) {
+        identity(input);
+        if (ids.has(input.taskId)) { throw new TypeError('Duplicate manifest taskId'); }
+        ids.add(input.taskId);
+    }
+    await Promise.all(document.assignments.map(async (input) => {
+        const request = assignment(input, registry);
+        await request.adapter.validate(request.spec);
+        request.adapter.resources(request.spec).forEach((key) => {
+            if (resources.has(key)) { throw new Error('Manifest resource already claimed'); }
+            resources.add(key);
+        });
+    }));
+}

package/src/application/runtime/pipelineAdapters.js

@@ -0,0 +1,60 @@
+import { clickhouseSink, mqttSink } from '../../infrastructure/streams/index.js';
+import activityTracking from '../../infrastructure/ingest/activity/activityTracking.js';
+import amqpMetricsIngest from '../../infrastructure/ingest/telemetry/amqpMetricsIngest.js';
+import amqpMqttRelay from '../../infrastructure/ingest/telemetry/amqpMqttRelay.js';
+import modbusPublish from '../../infrastructure/ingest/mqtt/modbusPublish.js';
+import mqttMetrics from '../../infrastructure/ingest/mqtt/mqttMetrics.js';
+import { parseModbusDeviceSpec } from '../../infrastructure/ingest/mqtt/modbusDeviceSpec.js';
+import compositeLifecycle from './compositeLifecycle.js';
+import resolveSecrets from './resolveSecrets.js';
+
+function configured(spec, context) {
+    const options = { maxRecords: spec.limits?.maxRecords, maxBytes: spec.limits?.maxBytes, budget: context.budget };
+    const defined = Object.fromEntries(Object.entries(options).filter(([, value]) => { return value !== undefined; }));
+    return { ...resolveSecrets(spec, context.secrets),
+        config: { ...resolveSecrets(spec.config, context.secrets), ...defined },
+        options: { ...resolveSecrets(spec.options, context.secrets), ...defined } };
+}
+function adapter(factory, required, resourceKeys = () => { return []; }) {
+    return {
+        validate(spec) {
+            required.forEach((key) => { if (!spec[key]) { throw new TypeError(`Missing pipeline ${key}`); } });
+        },
+        resources(spec) { return resourceKeys(spec); },
+        create(spec, context) {
+            let pipeline;
+            let stopped = false;
+            return {
+                start() {
+                    context.signal.throwIfAborted();
+                    if (stopped) { throw new Error('Pipeline stopped'); }
+                    pipeline ??= factory(configured(spec, context));
+                    return pipeline.start();
+                },
+                stop() { stopped = true; return pipeline?.stop(); }
+            };
+        }
+    };
+}
+function modbusResources(spec) {
+    const devices = spec.config.devices?.split(',').map(parseModbusDeviceSpec) ?? [];
+    const paths = devices.filter((device) => { return device.kind === 'rtu'; }).map((device) => { return `serial:${device.path}`; });
+    const addresses = spec.config.addresses ?? [];
+    addresses.filter((address) => { return address.startsWith('rtu://'); }).forEach((address) => {
+        paths.push(`serial:${address.slice(6).split(':')[0]}`);
+    });
+    return [...new Set(paths)];
+}
+function metrics(spec, factory) {
+    const sink = clickhouseSink(spec.clickhouseUrl, spec.table);
+    return compositeLifecycle({ outputs: [sink], inputs: [factory(sink)] });
+}
+export default function pipelineAdapters() {
+    return new Map([
+        ['modbus', adapter((spec) => { return modbusPublish(spec.url, spec.config); }, ['url', 'config'], modbusResources)],
+        ['activity', adapter((spec) => { return activityTracking(spec.lokiUrl, spec.clickhouseUrl, spec.query, spec.config); }, ['lokiUrl', 'clickhouseUrl', 'query', 'config'])],
+        ['amqp-relay', adapter((spec) => { return amqpMqttRelay(spec.url, spec.queue, mqttSink(spec.mqttUrl, spec.options), spec.options); }, ['url', 'queue', 'mqttUrl'])],
+        ['amqp-metrics', adapter((spec) => { return metrics(spec, (sink) => { return amqpMetricsIngest(spec.url, spec.queue, sink, spec.options); }); }, ['url', 'queue', 'clickhouseUrl', 'table'])],
+        ['mqtt-metrics', adapter((spec) => { return metrics(spec, (sink) => { return mqttMetrics(spec.url, sink, spec.topic, spec.config); }); }, ['url', 'topic', 'clickhouseUrl', 'table', 'config'])]
+    ]);
+}

package/src/application/runtime/resolveSecrets.js

@@ -0,0 +1,12 @@
+/** Resolve references only at resource construction; hashes and manifests retain refs. */
+export default function resolveSecrets(value, secrets) {
+    if (Array.isArray(value)) { return value.map((item) => { return resolveSecrets(item, secrets); }); }
+    if (!value || typeof value !== 'object') { return value; }
+    if (Object.hasOwn(value, '$secret')) {
+        if (Object.keys(value).length !== 1 || typeof value.$secret !== 'string') { throw new TypeError('Invalid secret reference'); }
+        const resolved = secrets?.get(value.$secret);
+        if (resolved === undefined || resolved === null) { throw new Error('Required collector secret is unavailable'); }
+        return resolved;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => { return [key, resolveSecrets(item, secrets)]; }));
+}

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 };
+}