@hotmeshio/long-tail 0.28.0 → 0.28.2

package/build/api/files.d.ts

@@ -10,9 +10,14 @@ export declare function getFileMetadata(input: {
 export declare function deleteFile(input: {
     filePath: string;
 }): Promise<LTApiResult>;
+/**
+ * Stores the bytes with their SHA-256. A caller that names the digest it
+ * expects gets 422 when the bytes received differ, and nothing is stored.
+ */
 export declare function uploadFile(input: {
     path: string;
     buffer: Buffer;
+    sha256?: string;
 }): Promise<LTApiResult>;
 export declare function generateSignedUrl(input: {
     filePath: string;

package/build/api/files.js

@@ -5,6 +5,7 @@ exports.getFileMetadata = getFileMetadata;
 exports.deleteFile = deleteFile;
 exports.uploadFile = uploadFile;
 exports.generateSignedUrl = generateSignedUrl;
+const crypto_1 = require("crypto");
 const storage_1 = require("../lib/storage");
 const mime_1 = require("../lib/storage/mime");
 const publish_1 = require("../lib/events/publish");
@@ -46,9 +47,25 @@ async function deleteFile(input) {
         return { status: 500, error: err.message };
     }
 }
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+/**
+ * Stores the bytes with their SHA-256. A caller that names the digest it
+ * expects gets 422 when the bytes received differ, and nothing is stored.
+ */
 async function uploadFile(input) {
+    if (input.sha256 !== undefined && !SHA256_HEX.test(input.sha256)) {
+        return { status: 400, error: 'sha256 must be 64 hex characters' };
+    }
+    const sha256 = (0, crypto_1.createHash)('sha256').update(input.buffer).digest('hex');
+    if (input.sha256 && input.sha256.toLowerCase() !== sha256) {
+        return {
+            status: 422,
+            error: 'sha256 does not match the bytes received',
+            data: { error: 'sha256 does not match the bytes received', path: input.path, expected: input.sha256.toLowerCase(), actual: sha256 },
+        };
+    }
     try {
-        const result = await (0, storage_1.getStorageBackend)().write(input.path, input.buffer);
+        const result = await (0, storage_1.getStorageBackend)().write(input.path, input.buffer, { sha256 });
         const contentType = (0, mime_1.mimeFromPath)(input.path);
         (0, publish_1.publishFileEvent)({
             type: 'file.stored',
@@ -58,7 +75,7 @@ async function uploadFile(input) {
         });
         return {
             status: 200,
-            data: { path: input.path, size: result.size, content_type: contentType },
+            data: { path: input.path, size: result.size, content_type: contentType, sha256 },
         };
     }
     catch (err) {

package/build/api/knowledge.d.ts

@@ -14,7 +14,8 @@ export declare function getEntry(input: {
 export declare function getEntryVersion(input: {
     domain: string;
     key: string;
-    version: number;
+    /** An edition number, or the label an edition carries. */
+    version: number | string;
 }): Promise<LTApiResult>;
 export declare function listEntryVersions(input: {
     domain: string;
@@ -26,6 +27,7 @@ export declare function storeEntry(input: {
     data: Record<string, any>;
     tags?: string[];
     replace?: boolean;
+    label?: string;
 }): Promise<LTApiResult>;
 export declare function setField(input: {
     domain: string;

package/build/lib/db/schemas/042_knowledge_edition_labels.sql

@@ -0,0 +1,9 @@
+-- An edition may carry a label: a name a lookup ref pins instead of the
+-- version number (a catalog revision, say). A label names one edition of an
+-- entry; editions without one are reached by number or as current.
+ALTER TABLE lt_knowledge_versions
+  ADD COLUMN IF NOT EXISTS label TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS lt_knowledge_versions_label_idx
+  ON lt_knowledge_versions (domain, key, label)
+  WHERE label IS NOT NULL;

package/build/lib/events/publish.js

@@ -18,12 +18,13 @@ const index_1 = require("./index");
 const matching_1 = require("./matching");
 const logger_1 = require("../logger");
 /**
- * Fire-and-forget publish helper. Swallows errors (best-effort).
+ * Fire-and-forget publish helper. Swallows errors (best-effort). The publish
+ * is noted at debug: a line's wire can carry many events a second.
  */
 function fireAndForget(event) {
     if (!index_1.eventRegistry.hasAdapters)
         return Promise.resolve();
-    logger_1.loggerRegistry.info(`[lt-pub] ${event.type} ${event.workflowId || ''} ${event.escalationId || event.taskId || ''}`);
+    logger_1.loggerRegistry.debug(`[lt-pub] ${event.type} ${event.workflowId || ''} ${event.escalationId || event.taskId || ''}`);
     return index_1.eventRegistry.publish(event).catch(() => { });
 }
 /**

package/build/lib/machines/line.d.ts

@@ -35,6 +35,7 @@ export declare function controllerId(line: LineDef): string;
 export declare function stationRole(process: string): string;
 export declare const DEFAULT_EXIT_ROLE = "line-exit";
 export declare const DEFAULT_OPERATOR_ROLE = "line-operator";
+export declare const DEFAULT_QUALITY_ROLE = "line-quality";
 /** The Long Tail role a machine resolves handoffs under. */
 export declare function machineRole(def: Pick<MachineDef, 'role' | 'process'>): string;
 /** Every station role on the line, once each, in route order. */
@@ -45,3 +46,5 @@ export declare function exitRole(line: LineDef): string;
 export declare function receiverRoles(line: LineDef): string[];
 /** The role of the person who decides failed handoffs and closes alarm and machine rows. */
 export declare function operatorRole(line: LineDef): string;
+/** The role of the people who decide units a machine finished on hold: release, rework or scrap. */
+export declare function qualityRole(line: LineDef): string;

package/build/lib/machines/line.js

@@ -5,7 +5,7 @@
  * several separated by commas.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_OPERATOR_ROLE = exports.DEFAULT_EXIT_ROLE = exports.CARRIER_ROLE = exports.ADDRESSING = void 0;
+exports.DEFAULT_QUALITY_ROLE = exports.DEFAULT_OPERATOR_ROLE = exports.DEFAULT_EXIT_ROLE = exports.CARRIER_ROLE = exports.ADDRESSING = void 0;
 exports.learnsAddress = learnsAddress;
 exports.validateLine = validateLine;
 exports.loadLine = loadLine;
@@ -20,6 +20,7 @@ exports.stationRoles = stationRoles;
 exports.exitRole = exitRole;
 exports.receiverRoles = receiverRoles;
 exports.operatorRole = operatorRole;
+exports.qualityRole = qualityRole;
 const fs_1 = require("fs");
 const protocol_1 = require("./protocol");
 /** How a line knows its machines' addresses (`LineDef.addressing`). */
@@ -109,6 +110,7 @@ function stationRole(process) {
 }
 exports.DEFAULT_EXIT_ROLE = 'line-exit';
 exports.DEFAULT_OPERATOR_ROLE = 'line-operator';
+exports.DEFAULT_QUALITY_ROLE = 'line-quality';
 /** The Long Tail role a machine resolves handoffs under. */
 function machineRole(def) {
     return def.role ?? stationRole(def.process);
@@ -129,3 +131,7 @@ function receiverRoles(line) {
 function operatorRole(line) {
     return line.roles?.operator ?? exports.DEFAULT_OPERATOR_ROLE;
 }
+/** The role of the people who decide units a machine finished on hold: release, rework or scrap. */
+function qualityRole(line) {
+    return line.roles?.quality ?? exports.DEFAULT_QUALITY_ROLE;
+}

package/build/lib/machines/protocol/codec.d.ts

@@ -20,6 +20,12 @@ export interface MachineCommand {
     attempt?: number;
     /** The command may have reached the machine before: sent earlier, or its row predates this gateway's takeover. */
     retry?: boolean;
+    /**
+     * When the command was issued, ISO 8601: the same on every send of this `cmdId`, by this gateway or the
+     * next, so a protocol that stamps a time repeats the first attempt. A dispatch or a command row takes the
+     * start of its validity round; any other command the time of its first send.
+     */
+    issuedAt?: string;
 }
 /** MQTT filters under each machine's topic, e.g. `job` or `alarm/+`. */
 export interface CodecChannels {

package/build/lib/machines/protocol/codec.js

@@ -83,7 +83,7 @@ function genericCodec(opts) {
             return receiptFrom === exports.RECEIPT_FROM.ARRIVED ? [seen] : inferReceipt(seen, receiptFrom);
         },
         encode(ident, command) {
-            return [{ topic: (0, topics_1.machineTopic)(opts.root, ident, constants_1.CHANNEL.CMD), payload: JSON.stringify((0, envelope_1.buildEnvelope)(ident, command)) }];
+            return [{ topic: (0, topics_1.machineTopic)(opts.root, ident, constants_1.CHANNEL.CMD), payload: JSON.stringify((0, envelope_1.buildEnvelope)(ident, command, { at: command.issuedAt })) }];
         },
     };
 }

package/build/lib/machines/protocol/contract.d.ts

@@ -17,3 +17,5 @@ export interface Inspection {
 }
 /** Validate one message. `retained` is the publisher's flag when the transport reports it. */
 export declare function inspectMessage(root: string, topic: string, raw: string | Buffer, retained?: boolean): Inspection;
+/** A receiver's report that it could read no id at all: a transfer failure on the read, naming no unit and no carrier. */
+export declare function isUnreadableRead(b: Record<string, any>): boolean;

package/build/lib/machines/protocol/contract.js

@@ -10,6 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.inspectMessage = inspectMessage;
+exports.isUnreadableRead = isUnreadableRead;
 const ajv_1 = __importDefault(require("ajv"));
 const constants_1 = require("./constants");
 const envelope_1 = require("./envelope");
@@ -41,7 +42,7 @@ const BODY = {
         jobs: { type: 'array', items: shape({ jobId: STR, units: { type: 'array', items: STR }, status: STR }) },
         alarms: { type: 'array', items: STR },
         cycles: INT0,
-    }),
+    }, ['bootId', 'software', 'recipe', 'cycles']),
     [topics_1.MESSAGE_KIND.JOB]: shape({
         event: oneOf(constants_1.JOB_EVENT), jobId: STR, unitId: STR, orderRef: STR, recipe: RECIPE, carrierId: STR_N, peer: STR_N,
         result: oneOf(constants_1.JOB_RESULT), reason: STR_N,
@@ -52,15 +53,15 @@ const BODY = {
         materials: { type: 'array', items: shape({ material: STR, lot: STR }) },
         startedAt: TS, endedAt: TS, durationMs: INT0, failure: oneOf(constants_1.TRANSFER_FAILURE),
         percent: { type: 'number', minimum: 0, maximum: 100 }, remainingSec: INT0, stage: STR, detail: { type: 'object' },
-    }, ['jobId', 'unitId', 'peer', 'result', 'reason', 'measurements', 'materials', 'startedAt', 'endedAt', 'durationMs', 'failure', 'percent', 'remainingSec', 'stage', 'detail']),
+    }, ['jobId', 'unitId', 'orderRef', 'peer', 'result', 'reason', 'measurements', 'materials', 'startedAt', 'endedAt', 'durationMs', 'failure', 'percent', 'remainingSec', 'stage', 'detail']),
     [topics_1.MESSAGE_KIND.ALARM]: shape({
         alarmId: STR, code: STR, level: oneOf(constants_1.LEVEL), text: STR, active: BOOL,
         raisedAt: TS, clearedAt: TS_N, clearedBy: STR_N, ackedBy: STR_N, ackedAt: TS_N,
-        zone: STR_N, autoClears: BOOL, action: STR_N, jobId: STR_N,
-    }),
+        zone: STR_N, autoClears: BOOL, action: STR_N, jobId: STR_N, needsPerson: BOOL,
+    }, ['needsPerson']),
     [topics_1.MESSAGE_KIND.TELEMETRY]: shape({ readings: { type: 'object', additionalProperties: NUM } }),
     [topics_1.MESSAGE_KIND.CMD]: shape({ cmdId: STR, op: oneOf(constants_1.OP), args: { type: 'object' } }),
-    [topics_1.MESSAGE_KIND.REPLY]: shape({ cmdId: STR, status: oneOf(constants_1.REPLY_STATUS), reason: STR, code: STR }, ['code']),
+    [topics_1.MESSAGE_KIND.REPLY]: shape({ cmdId: STR, status: oneOf(constants_1.REPLY_STATUS), reason: STR, code: STR, preparing: BOOL }, ['code', 'preparing']),
     [topics_1.MESSAGE_KIND.REPORT]: { type: 'object' },
 };
 const ajv = new ajv_1.default({ allErrors: true, strict: false });
@@ -95,6 +96,10 @@ function inspectMessage(root, topic, raw, retained) {
 }
 /** Job events a receiver may report naming only the carrier it scanned. */
 const CARRIER_EVENTS = [constants_1.JOB_EVENT.ARRIVED, constants_1.JOB_EVENT.TRANSFER_FAILED];
+/** A receiver's report that it could read no id at all: a transfer failure on the read, naming no unit and no carrier. */
+function isUnreadableRead(b) {
+    return b.event === constants_1.JOB_EVENT.TRANSFER_FAILED && b.failure === constants_1.TRANSFER_FAILURE.UNREADABLE_ID && b.unitId === undefined && typeof b.carrierId !== 'string';
+}
 function crossFieldRules(parsed, env, retained) {
     const out = [];
     const b = env.body ?? {};
@@ -105,8 +110,8 @@ function crossFieldRules(parsed, env, retained) {
     if (kind === topics_1.MESSAGE_KIND.ALARM && b.alarmId !== key)
         out.push('alarmId disagrees with the topic');
     if (kind === topics_1.MESSAGE_KIND.JOB) {
-        // A scan at a receiver may read only the carrier; every other job event names its unit and job.
-        const byCarrier = CARRIER_EVENTS.includes(b.event) && typeof b.carrierId === 'string';
+        // A scan at a receiver may read only the carrier, or nothing at all when the read failed; every other job event names its unit and job.
+        const byCarrier = CARRIER_EVENTS.includes(b.event) && (typeof b.carrierId === 'string' || isUnreadableRead(b));
         if (b.unitId === undefined && !byCarrier)
             out.push(`${b.event} without a unitId`);
         if (b.jobId === undefined && !byCarrier)

package/build/lib/machines/site/mosquitto-conf.d.ts

@@ -7,9 +7,10 @@
  * NATS, where JetStream keeps them.
  */
 import { type LineCodec } from '../protocol/codec';
-import { type Lines } from './site-conf';
+import { type LineDef } from '../line';
+import { type Lines, type TopicRoot } from './site-conf';
 export interface MosquittoConfOptions {
-    root: string;
+    root: TopicRoot;
     /** Certificate directory as the broker sees it. */
     certDir: string;
     /** Where the site NATS MQTT listener is, host:port. */
@@ -25,4 +26,7 @@ export declare function renderMosquittoConf(lines: Lines, opts: MosquittoConfOpt
  * the channels under its own name (%u), so its certificate's common name must be its address. On a line
  * that also declares addresses, a certificate named for a declared address is denied that station's channels.
  */
-export declare function renderMosquittoAcl(lines: Lines, codec: Pick<LineCodec, 'root' | 'channels' | 'topicFor'>): string;
+export type AclCodec = Pick<LineCodec, 'root' | 'channels' | 'topicFor'>;
+/** One codec for every line, or the codec of each line. */
+export type AclCodecs = AclCodec | ((line: LineDef) => AclCodec);
+export declare function renderMosquittoAcl(lines: Lines, codec: AclCodecs): string;

package/build/lib/machines/site/mosquitto-conf.js

@@ -26,7 +26,7 @@ remote_clientid ${(0, site_conf_1.bridgeId)(line)}
 cleansession false
 try_private false
 notifications false
-topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
+topic ${(0, site_conf_1.rootOf)(opts.root, line)}/${line.siteId}/${line.lineId}/# out 1
 `;
 }
 /** The broker for one line or several: one listener, one bridge per line. */
@@ -53,17 +53,12 @@ max_packet_size ${opts.maxPacketBytes ?? 262_144}
 
 ${list.map((line) => bridgeBlock(line, opts)).join('\n')}`;
 }
-/**
- * The codec's channels decide the topics: a machine writes its events and telemetry and reads its commands.
- * A station whose address the line learns has no user of its own: `pattern` rules give every certificate
- * the channels under its own name (%u), so its certificate's common name must be its address. On a line
- * that also declares addresses, a certificate named for a declared address is denied that station's channels.
- */
 function renderMosquittoAcl(lines, codec) {
     const list = (0, site_conf_1.linesOf)(lines);
     if (!list.length)
         throw new Error('renderMosquittoAcl needs at least one line');
-    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${list.map((line) => aclRules(line, codec)).join('\n\n')}\n`;
+    const codecOf = (line) => (typeof codec === 'function' ? codec(line) : codec);
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${list.map((line) => aclRules(line, codecOf(line))).join('\n\n')}\n`;
 }
 /** One line's rules: its stations, its controller, and the shadows a learning line needs. */
 function aclRules(line, codec) {

package/build/lib/machines/site/site-conf.d.ts

@@ -8,8 +8,11 @@
  * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
  */
 import { type LineDef } from '../line';
+/** One topic root for every line, or a root per line (lines on different codecs). */
+export type TopicRoot = string | ((line: LineDef) => string);
+export declare function rootOf(root: TopicRoot, line: LineDef): string;
 export interface SiteConfOptions {
-    root: string;
+    root: TopicRoot;
     gatewayUser: string;
     gatewayPassword: string;
     certDir: string;

package/build/lib/machines/site/site-conf.js

@@ -9,6 +9,7 @@
  * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.rootOf = rootOf;
 exports.bridgeId = bridgeId;
 exports.gatewayPublish = gatewayPublish;
 exports.linesOf = linesOf;
@@ -17,6 +18,9 @@ const line_1 = require("../line");
 const protocol_1 = require("../protocol");
 const permissions_1 = require("../../messaging/nats/permissions");
 const streams_1 = require("../transport/streams");
+function rootOf(root, line) {
+    return typeof root === 'string' ? root : root(line);
+}
 const q = JSON.stringify;
 /** The machine broker's bridge identity for a line. */
 function bridgeId(line) {
@@ -44,7 +48,7 @@ function renderSiteConf(lines, opts) {
     const list = linesOf(lines);
     if (!list.length)
         throw new Error('renderSiteConf needs at least one line');
-    const baseOf = (line) => (0, protocol_1.toSubject)(`${opts.root}/${line.siteId}/${line.lineId}`);
+    const baseOf = (line) => (0, protocol_1.toSubject)(`${rootOf(opts.root, line)}/${line.siteId}/${line.lineId}`);
     const bridge = list.map((line) => [
         `    { user: ${q(`CN=${bridgeId(line)}`)}, allowed_connection_types: ["MQTT"],`,
         `      permissions: { publish: [${q(`${baseOf(line)}.>`)}], subscribe: { deny: [">"] } } }`,

package/build/lib/machines/transport/nats-bus.d.ts

@@ -17,7 +17,11 @@ export interface NatsBusOptions {
     lineId: string;
     /** The codec's topics: which subjects are durable events and which are live telemetry. */
     codec: StreamCodec;
+    /** The codecs of every line on this site, so the streams keep all their subjects. */
+    siteCodecs?: StreamCodec[];
     nakDelayMs?: number;
+    /** Told once when the consumer can deliver nothing more, so the line can give its lead up and contend again. */
+    onLost?: (reason: string) => void;
 }
 export declare class NatsMachineBus implements MachineBus {
     private readonly opts;

package/build/lib/machines/transport/stream-bus.d.ts

@@ -3,7 +3,9 @@
  * line's durable consumer on LINE_EVENTS (replayed after a restart); telemetry
  * is read live, since it only proves a machine is alive. Commands leave through
  * an MQTT session at QoS 1 on the site broker, which queues them for a machine
- * that is away; retained machine state is read there too.
+ * that is away; retained machine state is read there too. The streams are
+ * ensured with every codec on the site, so lines on different roots share
+ * them, and a consumer the stream would feed nothing refuses to start.
  */
 import type { LTPubSub, LTStreams } from '../../../types/messaging';
 import type { MqttEndpoint } from '../../../services/machines/config';
@@ -19,7 +21,11 @@ export interface StreamBusOptions {
     lineId: string;
     /** The codec's topics: which subjects are durable events and which are live telemetry. */
     codec: StreamCodec;
+    /** The codecs of every line on this site; the streams keep all their subjects, whichever line starts last. */
+    siteCodecs?: StreamCodec[];
     nakDelayMs?: number;
+    /** Told once when the consumer can deliver nothing more, so the line can give its lead up and contend again. */
+    onLost?: (reason: string) => void;
 }
 export declare class StreamMachineBus implements MachineBus {
     private readonly opts;

package/build/lib/machines/transport/stream-bus.js

@@ -4,7 +4,9 @@
  * line's durable consumer on LINE_EVENTS (replayed after a restart); telemetry
  * is read live, since it only proves a machine is alive. Commands leave through
  * an MQTT session at QoS 1 on the site broker, which queues them for a machine
- * that is away; retained machine state is read there too.
+ * that is away; retained machine state is read there too. The streams are
+ * ensured with every codec on the site, so lines on different roots share
+ * them, and a consumer the stream would feed nothing refuses to start.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StreamMachineBus = void 0;
@@ -23,15 +25,27 @@ class StreamMachineBus {
         return `${this.opts.controllerId}-events`;
     }
     async connect() {
-        const { streams, codec, siteId, lineId, controllerId } = this.opts;
-        for (const spec of (0, streams_1.lineStreamSpecs)(codec))
+        const { streams, codec, siteId, lineId, controllerId, siteCodecs = [] } = this.opts;
+        for (const spec of (0, streams_1.lineStreamSpecs)([codec, ...siteCodecs]))
             await streams.ensureStream(spec);
-        await streams.ensureConsumer(streams_1.LINE_STREAM.EVENTS, (0, streams_1.lineEventConsumerSpec)(codec, siteId, lineId, this.durableName));
+        const consumer = (0, streams_1.lineEventConsumerSpec)(codec, siteId, lineId, this.durableName);
+        await streams.ensureConsumer(streams_1.LINE_STREAM.EVENTS, consumer);
+        const held = await streams.describeConsumer(streams_1.LINE_STREAM.EVENTS, consumer.name);
+        const reads = [...(held?.filterSubjects ?? [])].sort().join(', ');
+        const wants = [...consumer.filterSubjects].sort().join(', ');
+        if (reads !== wants) {
+            throw new Error(`${consumer.name} reads ${reads || 'nothing'} and not ${wants}; the consumer did not follow the line`);
+        }
+        const events = await streams.describeStream(streams_1.LINE_STREAM.EVENTS);
+        const missing = events ? (0, streams_1.uncoveredSubjects)(events, consumer.filterSubjects) : consumer.filterSubjects;
+        if (missing.length) {
+            throw new Error(`${streams_1.LINE_STREAM.EVENTS} keeps nothing of ${missing.join(', ')}; the stream holds ${events?.subjects.join(', ') ?? 'nothing'}`);
+        }
         this.session = await mqtt_session_1.MqttSession.open(this.opts.mqtt, controllerId);
     }
     async consume(handler) {
-        const { streams, pubsub, codec, siteId, lineId, nakDelayMs = 1_000 } = this.opts;
-        this.subs.push(await streams.consume(streams_1.LINE_STREAM.EVENTS, this.durableName, (m) => this.queue.run(() => handler({ topic: (0, protocol_1.toTopic)(m.subject), payload: m.payload, deliveries: m.deliveries })), { nakDelayMs }));
+        const { streams, pubsub, codec, siteId, lineId, nakDelayMs = 1_000, onLost } = this.opts;
+        this.subs.push(await streams.consume(streams_1.LINE_STREAM.EVENTS, this.durableName, (m) => this.queue.run(() => handler({ topic: (0, protocol_1.toTopic)(m.subject), payload: m.payload, deliveries: m.deliveries })), { nakDelayMs, onLost }));
         for (const subject of (0, streams_1.telemetrySubjects)(codec, siteId, lineId)) {
             this.subs.push(pubsub.subscribe(subject, (m) => void this.queue.run(() => handler({ topic: (0, protocol_1.toTopic)(m.subject), payload: m.payload, deliveries: 1 }))));
         }

package/build/lib/machines/transport/streams.d.ts

@@ -13,8 +13,17 @@ export declare const LINE_STREAM: {
 export type StreamCodec = Pick<LineCodec, 'root' | 'channels' | 'topicFor'>;
 /** An MQTT filter as a subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
 export declare function filterToSubject(filter: string): string;
-/** The line streams, for every line under the codec's root; a root alone means the generic layout. */
-export declare function lineStreamSpecs(codec: StreamCodec | string): StreamSpec[];
+/**
+ * The site's streams: every line under each codec's root, since lines on
+ * different protocols share one site NATS. A root alone means the generic
+ * layout; several codecs give the union of their subjects, sorted, so every
+ * line asks the site for the same stream whichever codec it lists first.
+ */
+export declare function lineStreamSpecs(codecs: StreamCodec | string | (StreamCodec | string)[]): StreamSpec[];
+/** Whether a stream subject pattern keeps everything a consumer filter would read. */
+export declare function subjectCovers(stream: string, filter: string): boolean;
+/** The consumer's filter subjects the stream keeps nothing of. */
+export declare function uncoveredSubjects(stream: Pick<StreamSpec, 'subjects'>, filters: string[]): string[];
 /** The telemetry subjects for one line, read live rather than replayed. */
 export declare function telemetrySubjects(codec: StreamCodec | string, siteId: string, lineId: string): string[];
 /**

package/build/lib/machines/transport/streams.js

@@ -8,6 +8,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LINE_STREAM = void 0;
 exports.filterToSubject = filterToSubject;
 exports.lineStreamSpecs = lineStreamSpecs;
+exports.subjectCovers = subjectCovers;
+exports.uncoveredSubjects = uncoveredSubjects;
 exports.telemetrySubjects = telemetrySubjects;
 exports.lineEventConsumerSpec = lineEventConsumerSpec;
 const codec_1 = require("../protocol/codec");
@@ -26,14 +28,40 @@ function filterToSubject(filter) {
 function subjectsFor(codec, channels, siteId, lineId) {
     return channels.map((c) => filterToSubject((0, codec_1.topicOf)(codec, { siteId, lineId }, c)));
 }
-/** The line streams, for every line under the codec's root; a root alone means the generic layout. */
-function lineStreamSpecs(codec) {
-    const c = codecOf(codec);
+/**
+ * The site's streams: every line under each codec's root, since lines on
+ * different protocols share one site NATS. A root alone means the generic
+ * layout; several codecs give the union of their subjects, sorted, so every
+ * line asks the site for the same stream whichever codec it lists first.
+ */
+function lineStreamSpecs(codecs) {
+    const list = (Array.isArray(codecs) ? codecs : [codecs]).map(codecOf);
+    const union = (channel) => [...new Set(list.flatMap((c) => subjectsFor(c, c.channels[channel])))].sort();
     return [
-        { name: exports.LINE_STREAM.EVENTS, subjects: subjectsFor(c, c.channels.events), maxAgeMs: 30 * DAY_MS },
-        { name: exports.LINE_STREAM.TELEMETRY, subjects: subjectsFor(c, c.channels.telemetry), maxAgeMs: 3 * DAY_MS },
+        { name: exports.LINE_STREAM.EVENTS, subjects: union('events'), maxAgeMs: 30 * DAY_MS },
+        { name: exports.LINE_STREAM.TELEMETRY, subjects: union('telemetry'), maxAgeMs: 3 * DAY_MS },
     ];
 }
+/** Whether a stream subject pattern keeps everything a consumer filter would read. */
+function subjectCovers(stream, filter) {
+    const s = stream.split('.');
+    const f = filter.split('.');
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '>')
+            return f.length > i;
+        if (i >= f.length)
+            return false;
+        if (f[i] === '>')
+            return false;
+        if (s[i] !== '*' && s[i] !== f[i])
+            return false;
+    }
+    return s.length === f.length;
+}
+/** The consumer's filter subjects the stream keeps nothing of. */
+function uncoveredSubjects(stream, filters) {
+    return filters.filter((f) => !stream.subjects.some((s) => subjectCovers(s, f)));
+}
 /** The telemetry subjects for one line, read live rather than replayed. */
 function telemetrySubjects(codec, siteId, lineId) {
     const c = codecOf(codec);

package/build/lib/messaging/memory.js

@@ -36,16 +36,23 @@ class MemoryStreams {
         else
             this.streams.set(spec.name, { spec, messages: [], seq: 0, consumers: new Map(), wake: new Set() });
     }
+    async describeStream(name) {
+        return this.streams.get(name)?.spec ?? null;
+    }
+    /** An existing consumer keeps its place while its subjects match; one whose subjects changed starts again. */
     async ensureConsumer(stream, spec) {
         const s = this.stream(stream);
         const existing = s.consumers.get(spec.name);
-        if (existing) {
-            existing.spec = { ...existing.spec, filterSubjects: spec.filterSubjects };
+        const same = (a, b) => [...a].sort().join('|') === [...b].sort().join('|');
+        if (existing && same(existing.spec.filterSubjects, spec.filterSubjects))
             return;
-        }
         const floor = (spec.startAt ?? constants_1.START_AT.NEW) === constants_1.START_AT.ALL ? 0 : s.seq;
         s.consumers.set(spec.name, { spec, floor, settled: new Set(), deliveries: new Map(), retryAt: new Map() });
     }
+    async describeConsumer(stream, name) {
+        const spec = this.streams.get(stream)?.consumers.get(name)?.spec;
+        return spec ? { ...spec, filterSubjects: [...spec.filterSubjects] } : null;
+    }
     async append(subject, payload) {
         const now = Date.now();
         for (const s of this.streams.values()) {

package/build/lib/messaging/nats/permissions.js

@@ -15,6 +15,7 @@ function jsPermissions({ streams, durable }) {
         `$JS.API.CONSUMER.CREATE.${s}.${durable}`,
         `$JS.API.CONSUMER.CREATE.${s}.${durable}.>`,
         `$JS.API.CONSUMER.DURABLE.CREATE.${s}.${durable}`,
+        `$JS.API.CONSUMER.DELETE.${s}.${durable}`,
         `$JS.API.CONSUMER.MSG.NEXT.${s}.${durable}`,
         `$JS.ACK.${s}.${durable}.>`,
     ]);

package/build/lib/messaging/nats/streams.d.ts

@@ -1,16 +1,31 @@
 /**
  * Durable streams on JetStream. A spec becomes a file-backed stream or an
- * explicit-ack durable consumer; ensuring either is safe on every boot, and an
- * existing consumer keeps its position while its subjects follow the spec.
+ * explicit-ack durable consumer; ensuring either is safe on every boot and
+ * from several lines at once. An existing consumer keeps its position while
+ * its subjects match the spec; one whose subjects changed is made again, since
+ * a position in another protocol's messages means nothing to this one.
  */
 import { type ConsumerConfig, type JetStreamClient, type JetStreamManager, type StreamConfig } from 'nats';
 import type { ConsumerSpec, Delivery, LTConsumeOptions, LTStreamMessage, LTStreams, LTSubscription, StreamSpec, Subject } from '../../../types/messaging';
 export declare function streamConfig(spec: StreamSpec): Partial<StreamConfig>;
 export declare function consumerConfig(spec: ConsumerSpec): Partial<ConsumerConfig>;
-/** Create the stream, or update an existing one to the spec. */
+/**
+ * Create the stream, or update an existing one to the spec. Two lines may
+ * ensure the same stream at once: the create that loses the race finds the
+ * stream in use and updates it instead.
+ */
 export declare function ensureStream(jsm: JetStreamManager, spec: StreamSpec): Promise<void>;
-/** Create the consumer, or move an existing one to the spec's subjects without losing its place. */
+/** The stream as JetStream holds it, or null when there is none. */
+export declare function describeStream(jsm: JetStreamManager, name: string): Promise<StreamSpec | null>;
+/**
+ * Create the consumer, or keep an existing one whose subjects match the spec,
+ * position and all. One whose subjects differ is deleted and made again at
+ * the stream's newest message, since its old position was in another
+ * protocol's messages.
+ */
 export declare function ensureConsumer(jsm: JetStreamManager, stream: string, spec: ConsumerSpec): Promise<void>;
+/** The consumer as JetStream holds it, or null when there is none. */
+export declare function describeConsumer(jsm: JetStreamManager, stream: string, name: string): Promise<ConsumerSpec | null>;
 export declare function payloadOf(m: {
     data: Uint8Array;
 }): string;
@@ -20,6 +35,8 @@ export declare class NatsStreams implements LTStreams {
     constructor(jsm: JetStreamManager, js: JetStreamClient);
     ensureStream(spec: StreamSpec): Promise<void>;
     ensureConsumer(stream: string, spec: ConsumerSpec): Promise<void>;
+    describeStream(name: string): Promise<StreamSpec | null>;
+    describeConsumer(stream: string, name: string): Promise<ConsumerSpec | null>;
     append(subject: Subject, payload: string): Promise<void>;
     /** One message at a time: the next is not taken until the handler settles this one. */
     consume(stream: string, consumer: string, handler: (m: LTStreamMessage) => Promise<Delivery>, opts?: LTConsumeOptions): Promise<LTSubscription>;