@hotmeshio/long-tail 0.27.0 → 0.28.1

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");
@@ -35,13 +36,13 @@ const ENVELOPE = shape({
 });
 const RECIPE = { anyOf: [shape({ id: STR, version: STR }), { type: 'null' }] };
 const BODY = {
-    [topics_1.MESSAGE_KIND.PRESENCE]: shape({ online: BOOL, software: STR }, ['software']),
+    [topics_1.MESSAGE_KIND.PRESENCE]: shape({ online: BOOL, software: STR, sessionId: STR, reason: STR }, ['software', 'sessionId', 'reason']),
     [topics_1.MESSAGE_KIND.SNAPSHOT]: shape({
         bootId: STR, software: STR, mode: oneOf(constants_1.MODE), enabled: BOOL, recipe: RECIPE,
         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 }),
+    [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

@@ -1,5 +1,5 @@
 /**
- * The machine broker (Mosquitto), rendered from the line. Machines speak
+ * The machine broker (Mosquitto), rendered from its lines. Machines speak
  * MQTT 5 to it over TLS, each with its own client certificate (the CN is
  * its username). The ACL lets a machine publish only its own channels and
  * read only its own commands, and lets the line controller command every
@@ -8,8 +8,9 @@
  */
 import { type LineCodec } from '../protocol/codec';
 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. */
@@ -17,11 +18,15 @@ export interface MosquittoConfOptions {
     aclFile: string;
     maxPacketBytes?: number;
 }
-export declare function renderMosquittoConf(line: LineDef, opts: MosquittoConfOptions): string;
+/** The broker for one line or several: one listener, one bridge per line. */
+export declare function renderMosquittoConf(lines: Lines, opts: MosquittoConfOptions): string;
 /**
  * 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.
  */
-export declare function renderMosquittoAcl(line: LineDef, 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

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * The machine broker (Mosquitto), rendered from the line. Machines speak
+ * The machine broker (Mosquitto), rendered from its lines. Machines speak
  * MQTT 5 to it over TLS, each with its own client certificate (the CN is
  * its username). The ACL lets a machine publish only its own channels and
  * read only its own commands, and lets the line controller command every
@@ -14,7 +14,26 @@ const envelope_1 = require("../protocol/envelope");
 const codec_1 = require("../protocol/codec");
 const line_1 = require("../line");
 const site_conf_1 = require("./site-conf");
-function renderMosquittoConf(line, opts) {
+/** One bridge connection per line, carrying the line's topics out to the site NATS. */
+function bridgeBlock(line, opts) {
+    return `connection ${line.siteId}-${line.lineId}-site-nats
+address ${opts.siteNats}
+bridge_protocol_version mqttv311
+bridge_cafile ${opts.certDir}/ca.pem
+bridge_certfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.pem
+bridge_keyfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.key
+remote_clientid ${(0, site_conf_1.bridgeId)(line)}
+cleansession false
+try_private false
+notifications false
+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. */
+function renderMosquittoConf(lines, opts) {
+    const list = (0, site_conf_1.linesOf)(lines);
+    if (!list.length)
+        throw new Error('renderMosquittoConf needs at least one line');
     return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
 persistence true
 persistence_location /mosquitto/data/
@@ -32,26 +51,17 @@ use_identity_as_username true
 acl_file ${opts.aclFile}
 max_packet_size ${opts.maxPacketBytes ?? 262_144}
 
-connection ${line.siteId}-${line.lineId}-site-nats
-address ${opts.siteNats}
-bridge_protocol_version mqttv311
-bridge_cafile ${opts.certDir}/ca.pem
-bridge_certfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.pem
-bridge_keyfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.key
-remote_clientid ${(0, site_conf_1.bridgeId)(line)}
-cleansession false
-try_private false
-notifications false
-topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
-`;
+${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(line, codec) {
+function renderMosquittoAcl(lines, codec) {
+    const list = (0, site_conf_1.linesOf)(lines);
+    if (!list.length)
+        throw new Error('renderMosquittoAcl needs at least one line');
+    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) {
     const { siteId, lineId } = line;
     const { events, telemetry, commands } = codec.channels;
     const own = (address, channels) => channels.map((c) => (0, codec_1.topicOf)(codec, { siteId, lineId, address }, c));
@@ -70,7 +80,7 @@ function renderMosquittoAcl(line, codec) {
         ...commands.map((c) => `topic write ${(0, codec_1.topicOf)(codec, { siteId, lineId }, c)}`),
         `topic read ${codec.root}/${siteId}/${lineId}/#`,
     ].join('\n');
-    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${[...learned, ...shadows, ...machines, controller].join('\n\n')}\n`;
+    return [...learned, ...shadows, ...machines, controller].join('\n\n');
 }
 /** Deny a declared station's channels to a certificate named for its address, which the patterns would grant. */
 function shadowRules(line, address, topics) {

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

@@ -1,5 +1,5 @@
 /**
- * The site's NATS server, rendered from the line. It runs JetStream and an
+ * The site's NATS server, rendered from its lines. It runs JetStream and an
  * MQTT listener that only the machine broker's bridge logs in to (by client
  * certificate; the CN is its user, and it may publish only under the line's
  * topics). The gateway logs in by password and may only keep and read the
@@ -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;
@@ -20,4 +23,11 @@ export interface SiteConfOptions {
 export declare function bridgeId(line: LineDef): string;
 /** What the gateway may publish: its streams' and its consumer's JetStream requests and acks, never a machine subject. */
 export declare function gatewayPublish(line: LineDef): string[];
-export declare function renderSiteConf(line: LineDef, opts: SiteConfOptions): string;
+/** One line, or every line the site runs. */
+export type Lines = LineDef | LineDef[];
+export declare function linesOf(lines: Lines): LineDef[];
+/**
+ * The site NATS for one line or several: one bridge user per line, one
+ * gateway user allowed every line's streams and subjects.
+ */
+export declare function renderSiteConf(lines: Lines, opts: SiteConfOptions): string;

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

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * The site's NATS server, rendered from the line. It runs JetStream and an
+ * The site's NATS server, rendered from its lines. It runs JetStream and an
  * MQTT listener that only the machine broker's bridge logs in to (by client
  * certificate; the CN is its user, and it may publish only under the line's
  * topics). The gateway logs in by password and may only keep and read the
@@ -9,13 +9,18 @@
  * 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;
 exports.renderSiteConf = renderSiteConf;
 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) {
@@ -25,18 +30,36 @@ function bridgeId(line) {
 function gatewayPublish(line) {
     return (0, permissions_1.jsPermissions)({ streams: Object.values(streams_1.LINE_STREAM), durable: `${(0, line_1.controllerId)(line)}-events` }).publish;
 }
-function renderSiteConf(line, opts) {
-    const base = (0, protocol_1.toSubject)(`${opts.root}/${line.siteId}/${line.lineId}`);
-    const bridge = [
+function linesOf(lines) {
+    return Array.isArray(lines) ? lines : [lines];
+}
+/** The server's name: the line for one line, the site when every line shares it, `site` otherwise. */
+function serverName(lines) {
+    if (lines.length === 1)
+        return `${lines[0].siteId}-${lines[0].lineId}`;
+    const sites = new Set(lines.map((l) => l.siteId));
+    return sites.size === 1 ? lines[0].siteId : 'site';
+}
+/**
+ * The site NATS for one line or several: one bridge user per line, one
+ * gateway user allowed every line's streams and subjects.
+ */
+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)(`${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(`${base}.>`)}], subscribe: { deny: [">"] } } }`,
-    ].join('\n');
+        `      permissions: { publish: [${q(`${baseOf(line)}.>`)}], subscribe: { deny: [">"] } } }`,
+    ].join('\n')).join('\n');
+    const publish = [...new Set(list.flatMap((line) => gatewayPublish(line)))];
     const gateway = [
         `    { user: ${q(opts.gatewayUser)}, password: ${q(opts.gatewayPassword)}, allowed_connection_types: ["STANDARD"],`,
-        `      permissions: { publish: ${q(gatewayPublish(line))}, subscribe: ${q(['_INBOX.>', `${base}.>`])} } }`,
+        `      permissions: { publish: ${q(publish)}, subscribe: ${q(['_INBOX.>', ...list.map((line) => `${baseOf(line)}.>`)])} } }`,
     ].join('\n');
     return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
-server_name: ${q(`${line.siteId}-${line.lineId}`)}
+server_name: ${q(serverName(list))}
 port: 4222
 http: 8222
 jetstream { store_dir: ${q(opts.storeDir)} }

package/build/lib/machines/transport/callback-feed.d.ts

@@ -14,5 +14,6 @@ export declare class CallbackEscalationFeed implements EscalationFeed {
     constructor(adapter: CallbackEventAdapter, nakDelayMs?: number);
     connect(): Promise<void>;
     consume(handler: (event: EscalationEvent) => Promise<MachineDisposition>): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }

package/build/lib/machines/transport/callback-feed.js

@@ -23,9 +23,12 @@ class CallbackEscalationFeed {
                 void this.redelivery.deliver(() => handler(event));
         });
     }
-    async close() {
+    async unsubscribe() {
         this.off?.();
         await this.redelivery.stop();
     }
+    async close() {
+        await this.unsubscribe();
+    }
 }
 exports.CallbackEscalationFeed = CallbackEscalationFeed;

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

@@ -26,6 +26,7 @@ export declare class MemoryMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }
 export declare class MemoryEscalationFeed implements EscalationFeed {
@@ -36,5 +37,6 @@ export declare class MemoryEscalationFeed implements EscalationFeed {
     emit(body: Record<string, any>): void;
     connect(): Promise<void>;
     consume(handler: (event: EscalationEvent) => Promise<Disposition>): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }

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

@@ -50,6 +50,9 @@ class MemoryMachineBus {
     async retained(filter) {
         return this.broker.retained(filter);
     }
+    async unsubscribe() {
+        this.broker.detach(this.durableName);
+    }
     async close() {
         this.broker.detach(this.durableName);
     }
@@ -72,6 +75,9 @@ class MemoryEscalationFeed {
             return event ? handler(event) : delivery_1.DISPOSITION.TERM;
         });
     }
+    async unsubscribe() {
+        this.broker.detach(this.durableName);
+    }
     async close() {
         this.broker.detach(this.durableName);
     }

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

@@ -19,6 +19,8 @@ export declare class MqttMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    /** Stops delivery in this process; the persistent session keeps its subscription, so messages queue for the next gateway. */
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
     private connected;
 }

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

@@ -30,6 +30,10 @@ class MqttMachineBus {
     retained(filter) {
         return this.connected().retained(filter);
     }
+    /** Stops delivery in this process; the persistent session keeps its subscription, so messages queue for the next gateway. */
+    async unsubscribe() {
+        await this.redelivery.stop();
+    }
     async close() {
         await this.redelivery.stop();
         await this.session?.close(true);

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

@@ -17,6 +17,8 @@ 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;
 }
 export declare class NatsMachineBus implements MachineBus {
@@ -31,6 +33,7 @@ export declare class NatsMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
     private stream;
 }

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

@@ -34,6 +34,9 @@ class NatsMachineBus {
     retained(filter) {
         return this.stream().retained(filter);
     }
+    async unsubscribe() {
+        await this.bus?.unsubscribe();
+    }
     async close() {
         await this.bus?.close();
         await this.provider.disconnect();

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

@@ -21,6 +21,7 @@ export declare class CoreEscalationFeed implements EscalationFeed {
     constructor(opts: CoreFeedOptions);
     connect(): Promise<void>;
     consume(handler: Handler): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }
 export {};

package/build/lib/machines/transport/nats-feed.js

@@ -40,9 +40,12 @@ class CoreEscalationFeed {
             },
         });
     }
-    async close() {
+    async unsubscribe() {
         this.sub?.unsubscribe();
         await this.redelivery.stop();
+    }
+    async close() {
+        await this.unsubscribe();
         await this.nc?.drain();
     }
 }

package/build/lib/machines/transport/pubsub-feed.d.ts

@@ -13,5 +13,6 @@ export declare class PubSubEscalationFeed implements EscalationFeed {
     constructor(pubsub: LTPubSub, nakDelayMs?: number);
     connect(): Promise<void>;
     consume(handler: (event: EscalationEvent) => Promise<Disposition>): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }

package/build/lib/machines/transport/pubsub-feed.js

@@ -31,9 +31,12 @@ class PubSubEscalationFeed {
                 void this.redelivery.deliver(() => handler(event));
         });
     }
-    async close() {
+    async unsubscribe() {
         await this.sub?.close();
         await this.redelivery.stop();
     }
+    async close() {
+        await this.unsubscribe();
+    }
 }
 exports.PubSubEscalationFeed = PubSubEscalationFeed;

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,6 +21,8 @@ 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;
 }
 export declare class StreamMachineBus implements MachineBus {
@@ -35,6 +39,8 @@ export declare class StreamMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    /** Stops the consumer and the live subscriptions; the MQTT session stays open for commands and receipts. */
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
     private mqtt;
 }

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,10 +25,16 @@ 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 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) {
@@ -42,10 +50,14 @@ class StreamMachineBus {
     retained(filter) {
         return this.mqtt().retained(filter);
     }
-    async close() {
+    /** Stops the consumer and the live subscriptions; the MQTT session stays open for commands and receipts. */
+    async unsubscribe() {
         for (const sub of this.subs.splice(0))
             await sub.close();
         await this.queue.drained();
+    }
+    async close() {
+        await this.unsubscribe();
         await this.session?.close(true);
     }
     mqtt() {

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

@@ -13,8 +13,16 @@ 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, in order.
+ */
+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,39 @@ 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, in order.
+ */
+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])))];
     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,6 +36,9 @@ 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;
+    }
     async ensureConsumer(stream, spec) {
         const s = this.stream(stream);
         const existing = s.consumers.get(spec.name);

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

@@ -9,6 +9,8 @@ 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. */
 export declare function ensureStream(jsm: JetStreamManager, spec: StreamSpec): Promise<void>;
+/** 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 move an existing one to the spec's subjects without losing its place. */
 export declare function ensureConsumer(jsm: JetStreamManager, stream: string, spec: ConsumerSpec): Promise<void>;
 export declare function payloadOf(m: {
@@ -20,6 +22,7 @@ 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>;
     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>;