@hotmeshio/long-tail 0.28.1 → 0.28.2

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/transport/nats-bus.d.ts

@@ -20,6 +20,8 @@ export interface NatsBusOptions {
     /** 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

@@ -24,6 +24,8 @@ export interface StreamBusOptions {
     /** 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

@@ -30,6 +30,12 @@ class StreamMachineBus {
             await streams.ensureStream(spec);
         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) {
@@ -38,8 +44,8 @@ class StreamMachineBus {
         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

@@ -16,7 +16,8 @@ export declare function filterToSubject(filter: string): string;
 /**
  * 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.
+ * 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. */

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

@@ -31,11 +31,12 @@ function subjectsFor(codec, channels, siteId, lineId) {
 /**
  * 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.
+ * 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])))];
+    const union = (channel) => [...new Set(list.flatMap((c) => subjectsFor(c, c.channels[channel])))].sort();
     return [
         { name: exports.LINE_STREAM.EVENTS, subjects: union('events'), maxAgeMs: 30 * DAY_MS },
         { name: exports.LINE_STREAM.TELEMETRY, subjects: union('telemetry'), maxAgeMs: 3 * DAY_MS },

package/build/lib/messaging/memory.js

@@ -39,16 +39,20 @@ class MemoryStreams {
     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,18 +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>;
 /** 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. */
+/**
+ * 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;
@@ -23,6 +36,7 @@ export declare class NatsStreams implements LTStreams {
     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>;

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

@@ -1,8 +1,10 @@
 "use strict";
 /**
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NatsStreams = void 0;
@@ -11,11 +13,15 @@ exports.consumerConfig = consumerConfig;
 exports.ensureStream = ensureStream;
 exports.describeStream = describeStream;
 exports.ensureConsumer = ensureConsumer;
+exports.describeConsumer = describeConsumer;
 exports.payloadOf = payloadOf;
 const nats_1 = require("nats");
 const constants_1 = require("../constants");
 const DEFAULT_ACK_WAIT_MS = 30_000;
 const DEFAULT_NAK_DELAY_MS = 1_000;
+/** Consumer events after which the consumer delivers nothing more: its stream or itself is gone, or the server fell silent. */
+const CONSUMER_LOST = new Set(['consumer_deleted', 'consumer_not_found', 'stream_not_found', 'heartbeats_missed']);
+const sameSubjects = (a = [], b = []) => [...a].sort().join('|') === [...b].sort().join('|');
 function streamConfig(spec) {
     return { name: spec.name, subjects: spec.subjects, max_age: (0, nats_1.nanos)(spec.maxAgeMs), storage: nats_1.StorageType.File };
 }
@@ -28,7 +34,11 @@ function consumerConfig(spec) {
         filter_subjects: spec.filterSubjects,
     };
 }
-/** 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.
+ */
 async function ensureStream(jsm, spec) {
     const config = streamConfig(spec);
     try {
@@ -37,8 +47,14 @@ async function ensureStream(jsm, spec) {
     catch (err) {
         if (!/stream not found/i.test(err?.message ?? ''))
             throw err;
-        await jsm.streams.add(config);
-        return;
+        try {
+            await jsm.streams.add(config);
+            return;
+        }
+        catch (added) {
+            if (!/already in use/i.test(added?.message ?? ''))
+                throw added;
+        }
     }
     await jsm.streams.update(spec.name, config);
 }
@@ -54,7 +70,12 @@ async function describeStream(jsm, name) {
         throw err;
     }
 }
-/** Create the consumer, or move an existing one to the spec's subjects without losing its place. */
+/**
+ * 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.
+ */
 async function ensureConsumer(jsm, stream, spec) {
     let existing;
     try {
@@ -66,10 +87,22 @@ async function ensureConsumer(jsm, stream, spec) {
         await jsm.consumers.add(stream, consumerConfig(spec));
         return;
     }
-    const want = [...spec.filterSubjects].sort();
-    const have = [...(existing.config.filter_subjects ?? [])].sort();
-    if (want.join('|') !== have.join('|'))
-        await jsm.consumers.update(stream, spec.name, { filter_subjects: spec.filterSubjects });
+    if (sameSubjects(spec.filterSubjects, existing.config.filter_subjects))
+        return;
+    await jsm.consumers.delete(stream, spec.name);
+    await jsm.consumers.add(stream, consumerConfig(spec));
+}
+/** The consumer as JetStream holds it, or null when there is none. */
+async function describeConsumer(jsm, stream, name) {
+    try {
+        const info = await jsm.consumers.info(stream, name);
+        return { name, filterSubjects: info.config.filter_subjects ?? (info.config.filter_subject ? [info.config.filter_subject] : []) };
+    }
+    catch (err) {
+        if (/consumer not found|stream not found/i.test(err?.message ?? ''))
+            return null;
+        throw err;
+    }
 }
 function payloadOf(m) {
     return Buffer.from(m.data).toString('utf8');
@@ -88,6 +121,9 @@ class NatsStreams {
     describeStream(name) {
         return describeStream(this.jsm, name);
     }
+    describeConsumer(stream, name) {
+        return describeConsumer(this.jsm, stream, name);
+    }
     async append(subject, payload) {
         await this.js.publish(subject, payload);
     }
@@ -95,6 +131,15 @@ class NatsStreams {
     async consume(stream, consumer, handler, opts = {}) {
         const nakDelayMs = opts.nakDelayMs ?? DEFAULT_NAK_DELAY_MS;
         const messages = await (await this.js.consumers.get(stream, consumer)).consume();
+        // The consumer's own status: once its stream or itself is gone, or the server fell silent, the reader is told.
+        void (async () => {
+            for await (const status of await messages.status()) {
+                if (!CONSUMER_LOST.has(String(status.type)))
+                    continue;
+                opts.onLost?.(String(status.type));
+                return;
+            }
+        })().catch(() => { });
         void (async () => {
             for await (const m of messages) {
                 const delivery = await handler({ subject: m.subject, payload: payloadOf(m), deliveries: m.info.deliveryCount })

package/build/services/machines/gateway/log.d.ts

@@ -32,6 +32,7 @@ export declare const GATEWAY_LOG: {
     readonly LEADING: "machine_gateway.line.leading";
     readonly STANDBY: "machine_gateway.line.standby";
     readonly LEADERSHIP_LOST: "machine_gateway.line.leadership_lost";
+    readonly WIRE_LOST: "machine_gateway.line.wire_lost";
     readonly START_FAILED: "machine_gateway.line.start_failed";
 };
 export type GatewayLogEvent = typeof GATEWAY_LOG[keyof typeof GATEWAY_LOG];

package/build/services/machines/gateway/log.js

@@ -37,6 +37,7 @@ exports.GATEWAY_LOG = {
     LEADING: 'machine_gateway.line.leading',
     STANDBY: 'machine_gateway.line.standby',
     LEADERSHIP_LOST: 'machine_gateway.line.leadership_lost',
+    WIRE_LOST: 'machine_gateway.line.wire_lost',
     START_FAILED: 'machine_gateway.line.start_failed',
 };
 exports.consoleLog = {

package/build/services/machines/leadership.d.ts

@@ -30,6 +30,8 @@ export declare class LineLeadership {
     private leadOnce;
     /** Lead while the lock is held; the error that ended it. */
     private holdLock;
+    /** The leader gives its turn up without stopping: `lost` runs, the lock goes, and the line contends again after the pause. */
+    relinquish(reason: string): void;
     /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
     stop(): Promise<void>;
 }

package/build/services/machines/leadership.js

@@ -62,7 +62,7 @@ class LineLeadership {
     async holdLock(client, lead) {
         const ended = new Promise((resolve) => {
             client.once('error', resolve);
-            this.endTurn = () => resolve(new Error('leadership stopped'));
+            this.endTurn = (err) => resolve(err ?? new Error('leadership stopped'));
         });
         try {
             await client.query(LOCK_SQL, [this.key]);
@@ -76,6 +76,12 @@ class LineLeadership {
             return err;
         }
     }
+    /** The leader gives its turn up without stopping: `lost` runs, the lock goes, and the line contends again after the pause. */
+    relinquish(reason) {
+        if (!this.leading)
+            return;
+        this.endTurn?.(new Error(reason));
+    }
     /** A leader unlocks; a replica still waiting drops its connection, which ends the wait. */
     async stop() {
         this.stopped = true;

package/build/services/machines/select.d.ts

@@ -19,7 +19,7 @@ export type LineMessaging = Pick<typeof messagingRegistry, 'streams' | 'pubsub'>
  * server of the site's own, which the bus connects to itself. `siteCodecs` are
  * the codecs of every line on the site, so the streams keep all their subjects.
  */
-export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: LineCodec, messaging?: LineMessaging, siteCodecs?: LineCodec[]): MachineBus;
+export declare function createMachineBus(config: MachineLineConfig, line: LineDef, codec?: LineCodec, messaging?: LineMessaging, siteCodecs?: LineCodec[], onLost?: (reason: string) => void): MachineBus;
 /** Long Tail's escalation events for the gateway; `in-process` needs the running instance's callback adapter. */
 export declare function createEscalationFeed(config: MachineLineConfig, line: LineDef, callbacks?: CallbackEventAdapter): EscalationFeed;
 /** One MQTT link per simulated machine; machines speak MQTT in every networked mode. */

package/build/services/machines/select.js

@@ -36,10 +36,10 @@ function defaultCodec(config, line) {
  * server of the site's own, which the bus connects to itself. `siteCodecs` are
  * the codecs of every line on the site, so the streams keep all their subjects.
  */
-function createMachineBus(config, line, codec = defaultCodec(config, line), messaging = messaging_1.messagingRegistry, siteCodecs = []) {
+function createMachineBus(config, line, codec = defaultCodec(config, line), messaging = messaging_1.messagingRegistry, siteCodecs = [], onLost) {
     switch (config.transport) {
         case config_1.MACHINE_TRANSPORT.NATS: {
-            const where = { mqtt: mqttOf(config), controllerId: (0, line_1.controllerId)(line), siteId: line.siteId, lineId: line.lineId, codec, siteCodecs };
+            const where = { mqtt: mqttOf(config), controllerId: (0, line_1.controllerId)(line), siteId: line.siteId, lineId: line.lineId, codec, siteCodecs, onLost };
             if (config.siteNatsUrl) {
                 return new nats_bus_1.NatsMachineBus({ natsUrl: config.siteNatsUrl, user: config.siteNatsUser, password: config.siteNatsPassword, ...where });
             }

package/build/services/machines/surface.js

@@ -103,8 +103,14 @@ class LineRun {
             return id;
         };
         const { config, line, codec } = this;
+        const where = { site: line.siteId, line: line.lineId };
+        // A wire that stops delivering ends this turn: the gateway stops, the line contends again and ensures its streams anew.
+        const onLost = (reason) => {
+            this.log.warn(log_1.GATEWAY_LOG.WIRE_LOST, { ...where, reason });
+            this.leadership.relinquish(`wire lost: ${reason}`);
+        };
         this.gateway = new gateway_1.MachineGateway({
-            bus: (0, select_1.createMachineBus)(config, line, codec, undefined, this.siteCodecs()),
+            bus: (0, select_1.createMachineBus)(config, line, codec, undefined, this.siteCodecs(), onLost),
             codec,
             rows: this.opts.rows,
             feed: (0, select_1.createEscalationFeed)(config, line, this.opts.callbacks),
@@ -121,7 +127,7 @@ class LineRun {
         });
         await this.gateway.start();
         this.ready = true;
-        this.log.info(log_1.GATEWAY_LOG.LEADING, { site: line.siteId, line: line.lineId });
+        this.log.info(log_1.GATEWAY_LOG.LEADING, where);
     }
 }
 class MachineSurface {

package/build/types/messaging.d.ts

@@ -47,15 +47,19 @@ export interface LTStreamMessage extends LTMessage {
 export interface LTConsumeOptions {
     /** Delay before a nak'd message is delivered again. */
     nakDelayMs?: number;
+    /** Told once when the consumer can deliver nothing more: its stream or itself is gone, or the server fell silent. */
+    onLost?: (reason: string) => void;
 }
 /** Durable streams: messages kept, delivered to named consumers in order, one at a time, until settled. */
 export interface LTStreams {
     /** Create the stream, or bring an existing one's subjects and age up to the spec. */
     ensureStream(spec: StreamSpec): Promise<void>;
-    /** Create the consumer, or bring an existing one's filter up to the spec; its position is kept. */
+    /** Create the consumer, or keep an existing one whose subjects match the spec; one whose subjects changed is made again. */
     ensureConsumer(stream: string, spec: ConsumerSpec): Promise<void>;
     /** The stream as it is now, or null when there is none. */
     describeStream(name: string): Promise<StreamSpec | null>;
+    /** The consumer as it is now, or null when there is none. */
+    describeConsumer(stream: string, name: string): Promise<ConsumerSpec | null>;
     /** Append a message; resolves once the stream holds it. */
     append(subject: Subject, payload: string): Promise<void>;
     /** Deliver the consumer's messages to `handler` one at a time; a thrown handler counts as a nak. */

package/docs/machines.md

@@ -327,8 +327,8 @@ The built-in `long-tail-machines` server offers the same surface to agents, gate
 ```
 
 - **Machines:** each machine logs in over MQTT 3.1.1 or 5 with its own certificate; the CN (`{site}-{line}-{address}`) is its username. The broker ACL lets it write only its own channels and read only its own commands. The line controller may command every machine on the line.
-- **Durable streams:** the bridge carries the line's topics one way into NATS, where only the bridge may publish them. JetStream keeps `LINE_EVENTS` (30 days) and `LINE_TELEMETRY` (3 days). The gateway reads through a durable consumer, `<controller>-events`, and may publish only JetStream requests and acks for its own streams and consumer; it cannot delete or purge them.
-- **One site, several codecs:** the streams are ensured with the subjects of every codec the surface runs on the site, so lines on different roots share `LINE_EVENTS` and `LINE_TELEMETRY` whichever line starts last; a gateway whose consumer the stream would feed nothing refuses to start and says which subjects are missing.
+- **Durable streams:** the bridge carries the line's topics one way into NATS, where only the bridge may publish them. JetStream keeps `LINE_EVENTS` (30 days) and `LINE_TELEMETRY` (3 days). The gateway reads through a durable consumer, `<controller>-events`, and may publish only JetStream requests and acks for its own streams and consumer, and delete that one consumer; it cannot delete or purge a stream. A consumer whose subjects no longer match the line (the line changed protocol) is made again at the stream's newest message rather than moved, so a position in another protocol's messages is never carried over. A consumer that can deliver nothing more (its stream or itself gone, the server silent) ends the leader's turn: the gateway stops, the line contends again and ensures its streams anew, so no line leads a wire it cannot read.
+- **One site, several codecs:** the streams are ensured with the subjects of every codec the surface runs on the site, sorted, so lines on different roots share `LINE_EVENTS` and `LINE_TELEMETRY` whichever line starts first or last, and two lines starting together on an empty JetStream agree on the stream (the create that loses the race updates instead); a gateway whose consumer the stream would feed nothing, or whose consumer did not follow its line, refuses to start and says which subjects are missing.
 - **Where the streams live:** by default in Long Tail's messaging ([events](events.md#messaging)), whose NATS server must run JetStream. The bridge then logs in to that server's edge account for the line (`Machines.edgeAccountFor`), which may publish only the line's subjects, so the edge reaches nothing of Long Tail's. With `MACHINE_SITE_NATS_URL`, the streams live instead in a NATS server of the site's own (`Machines.renderSiteConf`), and Long Tail's NATS stays inside Long Tail. Either way the gateway reads the same streams under the same consumer name.
 - **Escalation events:** the gateway inside Long Tail reads them in process. A standalone gateway subscribes to them over Long Tail's messaging.
 - **Commands:** the gateway publishes commands to the machine broker at QoS 1, so they queue for a machine that is away.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",