@hotmeshio/long-tail 0.26.0 → 0.28.0

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

@@ -1,67 +1,50 @@
 "use strict";
 /**
- * The gateway on the site NATS. Machine events come from the 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: a NATS publish reaches MQTT subscribers at QoS 0 and
- * would not wait for a machine that is away.
+ * The gateway on a NATS server of the site's own (MACHINE_SITE_NATS_*): the
+ * stream bus on a NATS messaging provider this bus connects and closes itself.
+ * With Long Tail's messaging configured, the stream bus runs on that instead.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NatsMachineBus = void 0;
-const nats_1 = require("nats");
-const protocol_1 = require("../protocol");
-const mqtt_session_1 = require("./mqtt-session");
-const nats_durable_1 = require("./nats-durable");
-const serial_1 = require("./serial");
-const streams_1 = require("./streams");
+const provider_1 = require("../../messaging/nats/provider");
+const stream_bus_1 = require("./stream-bus");
 class NatsMachineBus {
     constructor(opts) {
         this.opts = opts;
-        this.telemetry = [];
-        this.queue = new serial_1.SerialQueue();
+        this.provider = new provider_1.NatsMessagingProvider({ url: opts.natsUrl, user: opts.user, password: opts.password, name: opts.controllerId });
     }
     get durableName() {
         return `${this.opts.controllerId}-events`;
     }
     async connect() {
-        const { natsUrl, user, password, controllerId, siteId, lineId, codec } = this.opts;
-        this.nc = await (0, nats_1.connect)({ servers: natsUrl, user, pass: password, name: controllerId });
-        const jsm = await this.nc.jetstreamManager();
-        await (0, streams_1.ensureStreams)(jsm, (0, streams_1.lineStreamConfigs)(codec));
-        await (0, streams_1.ensureConsumer)(jsm, streams_1.LINE_STREAM.EVENTS, (0, streams_1.lineEventConsumer)(codec, siteId, lineId, this.durableName));
-        this.session = await mqtt_session_1.MqttSession.open(this.opts.mqtt, controllerId);
+        await this.provider.connect();
+        const streams = this.provider.streams;
+        if (!streams)
+            throw new Error(`the site NATS at ${this.opts.natsUrl} has no JetStream for the gateway`);
+        const { natsUrl: _url, user: _user, password: _password, ...rest } = this.opts;
+        this.bus = new stream_bus_1.StreamMachineBus({ ...rest, streams, pubsub: this.provider.pubsub });
+        await this.bus.connect();
     }
-    async consume(handler) {
-        const nc = this.nats();
-        const { codec, siteId, lineId, nakDelayMs = 1_000 } = this.opts;
-        this.messages = await (0, nats_durable_1.readDurable)(nc.jetstream(), streams_1.LINE_STREAM.EVENTS, this.durableName, this.queue, (m) => handler({ topic: (0, protocol_1.toTopic)(m.subject), payload: (0, nats_durable_1.payloadOf)(m), deliveries: m.info.deliveryCount }), nakDelayMs);
-        this.telemetry = (0, streams_1.telemetrySubjects)(codec, siteId, lineId).map((subject) => nc.subscribe(subject, {
-            callback: (_err, m) => void this.queue.run(() => handler({ topic: (0, protocol_1.toTopic)(m.subject), payload: (0, nats_durable_1.payloadOf)(m), deliveries: 1 })),
-        }));
+    consume(handler) {
+        return this.stream().consume(handler);
     }
-    async publish(topic, payload, opts = {}) {
-        await this.mqtt().publish(topic, payload, 1, opts.retain ?? false);
+    publish(topic, payload, opts) {
+        return this.stream().publish(topic, payload, opts);
     }
     retained(filter) {
-        return this.mqtt().retained(filter);
+        return this.stream().retained(filter);
     }
-    async close() {
-        for (const sub of this.telemetry)
-            sub.unsubscribe();
-        await this.messages?.close();
-        await this.queue.drained();
-        await this.session?.close(true);
-        await this.nc?.drain();
+    async unsubscribe() {
+        await this.bus?.unsubscribe();
     }
-    nats() {
-        if (!this.nc)
-            throw new Error('NATS bus used before connect()');
-        return this.nc;
+    async close() {
+        await this.bus?.close();
+        await this.provider.disconnect();
     }
-    mqtt() {
-        if (!this.session)
+    stream() {
+        if (!this.bus)
             throw new Error('NATS bus used before connect()');
-        return this.session;
+        return this.bus;
     }
 }
 exports.NatsMachineBus = NatsMachineBus;

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

@@ -8,7 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CoreEscalationFeed = exports.LT_ESCALATION_SUBJECTS = void 0;
 const nats_1 = require("nats");
-const nats_durable_1 = require("./nats-durable");
+const streams_1 = require("../../messaging/nats/streams");
 const serial_1 = require("./serial");
 const delivery_1 = require("./delivery");
 /** Long Tail publishes every LTEvent as `lt.events.<type>`. */
@@ -34,15 +34,18 @@ class CoreEscalationFeed {
             throw new Error('escalation feed used before connect()');
         this.sub = this.nc.subscribe(exports.LT_ESCALATION_SUBJECTS, {
             callback: (_err, m) => {
-                const event = decode((0, nats_durable_1.payloadOf)(m));
+                const event = decode((0, streams_1.payloadOf)(m));
                 if (event)
                     void this.redelivery.deliver(() => handler(event));
             },
         });
     }
-    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

@@ -0,0 +1,18 @@
+/**
+ * Long Tail's escalation events for a gateway running outside Long Tail, over
+ * Long Tail's messaging pub/sub. Nothing is replayed; a not-yet-actionable
+ * event is retried in this process, and the gateway reconciles open rows when
+ * it starts leading a line.
+ */
+import type { LTPubSub } from '../../../types/messaging';
+import { type Disposition, type EscalationEvent, type EscalationFeed } from './delivery';
+export declare class PubSubEscalationFeed implements EscalationFeed {
+    private readonly pubsub;
+    private sub?;
+    private readonly redelivery;
+    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

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Long Tail's escalation events for a gateway running outside Long Tail, over
+ * Long Tail's messaging pub/sub. Nothing is replayed; a not-yet-actionable
+ * event is retried in this process, and the gateway reconciles open rows when
+ * it starts leading a line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PubSubEscalationFeed = void 0;
+const constants_1 = require("../../messaging/constants");
+const serial_1 = require("./serial");
+const delivery_1 = require("./delivery");
+class PubSubEscalationFeed {
+    constructor(pubsub, nakDelayMs = 1_000) {
+        this.pubsub = pubsub;
+        this.redelivery = new serial_1.LocalRedelivery(new serial_1.SerialQueue(), nakDelayMs);
+    }
+    async connect() {
+        // The shared connection belongs to Long Tail's messaging registry.
+    }
+    async consume(handler) {
+        this.sub = this.pubsub.subscribe(constants_1.LT_SUBJECTS.ESCALATIONS, (m) => {
+            let event = null;
+            try {
+                event = (0, delivery_1.toEscalationEvent)(JSON.parse(m.payload));
+            }
+            catch {
+                event = null;
+            }
+            if (event)
+                void this.redelivery.deliver(() => handler(event));
+        });
+    }
+    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

@@ -0,0 +1,42 @@
+/**
+ * The gateway on Long Tail's messaging capability. Machine events come from the
+ * 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.
+ */
+import type { LTPubSub, LTStreams } from '../../../types/messaging';
+import type { MqttEndpoint } from '../../../services/machines/config';
+import { type StreamCodec } from './streams';
+import type { Disposition, InboundMessage, MachineBus } from './delivery';
+export interface StreamBusOptions {
+    streams: LTStreams;
+    pubsub: LTPubSub;
+    mqtt: MqttEndpoint;
+    /** The gateway's broker identity; also its MQTT client id and the root of its consumer's name. */
+    controllerId: string;
+    siteId: string;
+    lineId: string;
+    /** The codec's topics: which subjects are durable events and which are live telemetry. */
+    codec: StreamCodec;
+    nakDelayMs?: number;
+}
+export declare class StreamMachineBus implements MachineBus {
+    private readonly opts;
+    private session?;
+    private subs;
+    /** Events and telemetry reach the gateway one at a time, in arrival order. */
+    private readonly queue;
+    constructor(opts: StreamBusOptions);
+    get durableName(): string;
+    connect(): Promise<void>;
+    consume(handler: (msg: InboundMessage) => Promise<Disposition>): Promise<void>;
+    publish(topic: string, payload: string, opts?: {
+        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

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * The gateway on Long Tail's messaging capability. Machine events come from the
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamMachineBus = void 0;
+const protocol_1 = require("../protocol");
+const mqtt_session_1 = require("./mqtt-session");
+const serial_1 = require("./serial");
+const streams_1 = require("./streams");
+class StreamMachineBus {
+    constructor(opts) {
+        this.opts = opts;
+        this.subs = [];
+        /** Events and telemetry reach the gateway one at a time, in arrival order. */
+        this.queue = new serial_1.SerialQueue();
+    }
+    get durableName() {
+        return `${this.opts.controllerId}-events`;
+    }
+    async connect() {
+        const { streams, codec, siteId, lineId, controllerId } = this.opts;
+        for (const spec of (0, streams_1.lineStreamSpecs)(codec))
+            await streams.ensureStream(spec);
+        await streams.ensureConsumer(streams_1.LINE_STREAM.EVENTS, (0, streams_1.lineEventConsumerSpec)(codec, siteId, lineId, this.durableName));
+        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 }));
+        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 }))));
+        }
+    }
+    async publish(topic, payload, opts = {}) {
+        await this.mqtt().publish(topic, payload, 1, opts.retain ?? false);
+    }
+    retained(filter) {
+        return this.mqtt().retained(filter);
+    }
+    /** 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() {
+        if (!this.session)
+            throw new Error('stream bus used before connect()');
+        return this.session;
+    }
+}
+exports.StreamMachineBus = StreamMachineBus;

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

@@ -1,9 +1,9 @@
 /**
- * The site's durable log. Machine events and telemetry each land in a
- * JetStream stream; the gateway reads events through a durable consumer, so
- * a restart or a link outage replays instead of losing.
+ * The line's durable log, as specs for the messaging capability. Machine
+ * events and telemetry each land in a stream; the gateway reads events through
+ * a durable consumer, so a restart or a link outage replays instead of losing.
  */
-import { type ConsumerConfig, type JetStreamManager, type StreamConfig } from 'nats';
+import type { ConsumerSpec, StreamSpec } from '../../../types/messaging';
 import { type LineCodec } from '../protocol/codec';
 export declare const LINE_STREAM: {
     readonly EVENTS: "LINE_EVENTS";
@@ -11,18 +11,14 @@ export declare const LINE_STREAM: {
 };
 /** What the streams need from a codec: its root, channels and topic layout. */
 export type StreamCodec = Pick<LineCodec, 'root' | 'channels' | 'topicFor'>;
-/** An MQTT filter as a NATS subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
+/** An MQTT filter as a subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
 export declare function filterToSubject(filter: string): string;
-/** The site's streams, for every line under the codec's root; a root alone means the generic layout. */
-export declare function lineStreamConfigs(codec: StreamCodec | string): Partial<StreamConfig>[];
+/** 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 telemetry subjects for one line, read live rather than replayed. */
 export declare function telemetrySubjects(codec: StreamCodec | string, siteId: string, lineId: string): string[];
 /**
- * A durable consumer. It starts at new messages the first time (open rows
- * are reconciled at boot); after that its position survives restarts.
+ * One line's event consumer. It starts at new messages the first time (open
+ * rows are reconciled at boot); after that its position survives restarts.
  */
-export declare function durableConsumer(name: string, filterSubjects: string[]): Partial<ConsumerConfig>;
-export declare function lineEventConsumer(codec: StreamCodec | string, siteId: string, lineId: string, name: string): Partial<ConsumerConfig>;
-/** Create or update each stream, then the consumer. Safe on every boot. */
-export declare function ensureStreams(jsm: JetStreamManager, streams: Partial<StreamConfig>[]): Promise<void>;
-export declare function ensureConsumer(jsm: JetStreamManager, stream: string, config: Partial<ConsumerConfig>): Promise<void>;
+export declare function lineEventConsumerSpec(codec: StreamCodec | string, siteId: string, lineId: string, name: string): ConsumerSpec;

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

@@ -1,19 +1,15 @@
 "use strict";
 /**
- * The site's durable log. Machine events and telemetry each land in a
- * JetStream stream; the gateway reads events through a durable consumer, so
- * a restart or a link outage replays instead of losing.
+ * The line's durable log, as specs for the messaging capability. Machine
+ * events and telemetry each land in a stream; the gateway reads events through
+ * a durable consumer, so a restart or a link outage replays instead of losing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LINE_STREAM = void 0;
 exports.filterToSubject = filterToSubject;
-exports.lineStreamConfigs = lineStreamConfigs;
+exports.lineStreamSpecs = lineStreamSpecs;
 exports.telemetrySubjects = telemetrySubjects;
-exports.durableConsumer = durableConsumer;
-exports.lineEventConsumer = lineEventConsumer;
-exports.ensureStreams = ensureStreams;
-exports.ensureConsumer = ensureConsumer;
-const nats_1 = require("nats");
+exports.lineEventConsumerSpec = lineEventConsumerSpec;
 const codec_1 = require("../protocol/codec");
 exports.LINE_STREAM = {
     EVENTS: 'LINE_EVENTS',
@@ -22,71 +18,32 @@ exports.LINE_STREAM = {
 const DAY_MS = 86_400_000;
 const ACK_WAIT_MS = 30_000;
 const GENERIC = (root) => ({ root, channels: codec_1.GENERIC_CHANNELS });
-/** An MQTT filter as a NATS subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
+const codecOf = (codec) => (typeof codec === 'string' ? GENERIC(codec) : codec);
+/** An MQTT filter as a subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
 function filterToSubject(filter) {
     return filter.split('/').map((level) => (level === '+' ? '*' : level === '#' ? '>' : level)).join('.');
 }
 function subjectsFor(codec, channels, siteId, lineId) {
     return channels.map((c) => filterToSubject((0, codec_1.topicOf)(codec, { siteId, lineId }, c)));
 }
-/** The site's streams, for every line under the codec's root; a root alone means the generic layout. */
-function lineStreamConfigs(codec) {
-    const c = typeof codec === 'string' ? GENERIC(codec) : codec;
+/** 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);
     return [
-        { name: exports.LINE_STREAM.EVENTS, subjects: subjectsFor(c, c.channels.events), max_age: (0, nats_1.nanos)(30 * DAY_MS), storage: nats_1.StorageType.File },
-        { name: exports.LINE_STREAM.TELEMETRY, subjects: subjectsFor(c, c.channels.telemetry), max_age: (0, nats_1.nanos)(3 * DAY_MS), storage: nats_1.StorageType.File },
+        { 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 },
     ];
 }
 /** The telemetry subjects for one line, read live rather than replayed. */
 function telemetrySubjects(codec, siteId, lineId) {
-    const c = typeof codec === 'string' ? GENERIC(codec) : codec;
+    const c = codecOf(codec);
     return subjectsFor(c, c.channels.telemetry, siteId, lineId);
 }
 /**
- * A durable consumer. It starts at new messages the first time (open rows
- * are reconciled at boot); after that its position survives restarts.
+ * One line's event consumer. It starts at new messages the first time (open
+ * rows are reconciled at boot); after that its position survives restarts.
  */
-function durableConsumer(name, filterSubjects) {
-    return {
-        durable_name: name,
-        ack_policy: nats_1.AckPolicy.Explicit,
-        deliver_policy: nats_1.DeliverPolicy.New,
-        ack_wait: (0, nats_1.nanos)(ACK_WAIT_MS),
-        filter_subjects: filterSubjects,
-    };
-}
-function lineEventConsumer(codec, siteId, lineId, name) {
-    const c = typeof codec === 'string' ? GENERIC(codec) : codec;
-    return durableConsumer(name, subjectsFor(c, c.channels.events, siteId, lineId));
-}
-/** Create or update each stream, then the consumer. Safe on every boot. */
-async function ensureStreams(jsm, streams) {
-    for (const config of streams) {
-        try {
-            await jsm.streams.info(config.name);
-            await jsm.streams.update(config.name, config);
-        }
-        catch (err) {
-            if (!/stream not found/i.test(err?.message ?? ''))
-                throw err;
-            await jsm.streams.add(config);
-        }
-    }
-}
-async function ensureConsumer(jsm, stream, config) {
-    let existing;
-    try {
-        existing = await jsm.consumers.info(stream, config.durable_name);
-    }
-    catch (err) {
-        if (!/consumer not found/i.test(err?.message ?? ''))
-            throw err;
-        await jsm.consumers.add(stream, config);
-        return;
-    }
-    // The consumer keeps its position; only its subjects follow the codec's channels.
-    const want = [...(config.filter_subjects ?? [])].sort();
-    const have = [...(existing.config.filter_subjects ?? [])].sort();
-    if (want.join('|') !== have.join('|'))
-        await jsm.consumers.update(stream, config.durable_name, { filter_subjects: config.filter_subjects });
+function lineEventConsumerSpec(codec, siteId, lineId, name) {
+    const c = codecOf(codec);
+    return { name, filterSubjects: subjectsFor(c, c.channels.events, siteId, lineId), ackWaitMs: ACK_WAIT_MS, startAt: 'new' };
 }

package/build/lib/messaging/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which messaging provider a deployment runs, from start() or the environment.
+ * Precedence: an explicit provider, then `messaging.nats` or `messaging.memory`,
+ * then LT_MESSAGING with LT_NATS_*, then `events.nats` (the same NATS, configured
+ * as events always have been). With none, Long Tail runs without messaging.
+ */
+import type { LTMessagingProvider } from '../../types/messaging';
+import type { LTStartConfig } from '../../types/startup';
+export declare const MESSAGING_KIND: {
+    readonly NATS: "nats";
+    readonly MEMORY: "memory";
+};
+/** What browsers need to reach the provider's events: a public WebSocket URL, a proxy target, a credential. */
+export interface MessagingWs {
+    url?: string;
+    proxy?: string;
+    token?: string;
+}
+export interface ResolvedMessaging {
+    provider: LTMessagingProvider | null;
+    ws: MessagingWs;
+}
+type Env = Record<string, string | undefined>;
+export declare function resolveMessaging(start: Pick<LTStartConfig, 'messaging' | 'events'>, env?: Env): ResolvedMessaging;
+export {};

package/build/lib/messaging/config.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Which messaging provider a deployment runs, from start() or the environment.
+ * Precedence: an explicit provider, then `messaging.nats` or `messaging.memory`,
+ * then LT_MESSAGING with LT_NATS_*, then `events.nats` (the same NATS, configured
+ * as events always have been). With none, Long Tail runs without messaging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESSAGING_KIND = void 0;
+exports.resolveMessaging = resolveMessaging;
+const config_1 = require("../../modules/config");
+const memory_1 = require("./memory");
+const provider_1 = require("./nats/provider");
+exports.MESSAGING_KIND = { NATS: 'nats', MEMORY: 'memory' };
+const NONE = { provider: null, ws: {} };
+function fromEnv(env) {
+    const kind = env.LT_MESSAGING;
+    if (!kind)
+        return null;
+    if (kind === exports.MESSAGING_KIND.MEMORY)
+        return { provider: new memory_1.MemoryMessagingProvider(), ws: {} };
+    if (kind !== exports.MESSAGING_KIND.NATS)
+        throw new Error(`LT_MESSAGING="${kind}" is not one of ${Object.values(exports.MESSAGING_KIND).join(', ')}`);
+    const url = env.LT_NATS_URL;
+    if (!url)
+        throw new Error('LT_MESSAGING=nats needs LT_NATS_URL');
+    const token = env.LT_NATS_TOKEN || undefined;
+    return {
+        provider: new provider_1.NatsMessagingProvider({ url, token, user: env.LT_NATS_USER || undefined, password: env.LT_NATS_PASSWORD || undefined, name: 'long-tail' }),
+        ws: { url: env.LT_NATS_WS_URL || undefined, proxy: env.LT_NATS_WS_PROXY || undefined, token },
+    };
+}
+function resolveMessaging(start, env = process.env) {
+    const m = start.messaging;
+    if (m?.provider)
+        return { provider: m.provider, ws: m.nats?.ws ?? {} };
+    if (m?.nats) {
+        const { ws, ...nats } = m.nats;
+        return { provider: new provider_1.NatsMessagingProvider({ name: 'long-tail', ...nats }), ws: { ...ws, token: ws?.token ?? nats.token } };
+    }
+    if (m?.memory)
+        return { provider: new memory_1.MemoryMessagingProvider(), ws: {} };
+    const configured = fromEnv(env);
+    if (configured)
+        return configured;
+    const legacy = start.events?.nats;
+    if (legacy) {
+        const token = legacy.token || config_1.config.NATS_TOKEN || undefined;
+        return {
+            provider: new provider_1.NatsMessagingProvider({ url: legacy.url || config_1.config.NATS_URL, token, name: 'long-tail' }),
+            ws: { url: legacy.wsUrl || config_1.config.NATS_WS_URL || undefined, proxy: legacy.wsProxy, token },
+        };
+    }
+    return NONE;
+}

package/build/lib/messaging/constants.d.ts

@@ -0,0 +1,26 @@
+/** Deliveries, log events and subjects for the messaging capability. */
+/** What a consumer does with a stream message. */
+export declare const DELIVERY: {
+    /** Handled; do not deliver again. */
+    readonly ACK: "ack";
+    /** Not yet actionable; deliver again after a delay. */
+    readonly NAK: "nak";
+    /** Never actionable; drop it. */
+    readonly TERM: "term";
+};
+/** Where a new consumer starts: only messages appended after it, or the whole retained history. */
+export declare const START_AT: {
+    readonly NEW: "new";
+    readonly ALL: "all";
+};
+export declare const MESSAGING_LOG: {
+    readonly CONNECTED: "messaging.provider.connected";
+    readonly DISCONNECTED: "messaging.provider.disconnected";
+    readonly CONNECT_FAILED: "messaging.provider.connect_failed";
+    readonly STREAMS_UNAVAILABLE: "messaging.provider.streams_unavailable";
+};
+/** Subjects Long Tail itself publishes under. */
+export declare const LT_SUBJECTS: {
+    readonly EVENTS: "lt.events";
+    readonly ESCALATIONS: "lt.events.system.escalation.>";
+};

package/build/lib/messaging/constants.js

@@ -0,0 +1,26 @@
+"use strict";
+/** Deliveries, log events and subjects for the messaging capability. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LT_SUBJECTS = exports.MESSAGING_LOG = exports.START_AT = exports.DELIVERY = void 0;
+/** What a consumer does with a stream message. */
+exports.DELIVERY = {
+    /** Handled; do not deliver again. */
+    ACK: 'ack',
+    /** Not yet actionable; deliver again after a delay. */
+    NAK: 'nak',
+    /** Never actionable; drop it. */
+    TERM: 'term',
+};
+/** Where a new consumer starts: only messages appended after it, or the whole retained history. */
+exports.START_AT = { NEW: 'new', ALL: 'all' };
+exports.MESSAGING_LOG = {
+    CONNECTED: 'messaging.provider.connected',
+    DISCONNECTED: 'messaging.provider.disconnected',
+    CONNECT_FAILED: 'messaging.provider.connect_failed',
+    STREAMS_UNAVAILABLE: 'messaging.provider.streams_unavailable',
+};
+/** Subjects Long Tail itself publishes under. */
+exports.LT_SUBJECTS = {
+    EVENTS: 'lt.events',
+    ESCALATIONS: 'lt.events.system.escalation.>',
+};

package/build/lib/messaging/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The messaging registry: one provider, registered at startup and shared by
+ * every part of Long Tail that needs pub/sub or durable streams (events, the
+ * machine surface). Asking for messaging that is not configured fails loudly,
+ * because a caller that gets nothing back would believe it was handled.
+ */
+import type { LTMessagingProvider, LTPubSub, LTStreams } from '../../types/messaging';
+declare class LTMessagingRegistry {
+    private current;
+    /** Register the provider; replaces any registered before. Call before connect(). */
+    register(provider: LTMessagingProvider): void;
+    get hasProvider(): boolean;
+    get provider(): LTMessagingProvider;
+    get pubsub(): LTPubSub;
+    get streams(): LTStreams;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /** Forget the provider (tests). */
+    clear(): void;
+}
+export declare const messagingRegistry: LTMessagingRegistry;
+export { MemoryMessagingProvider } from './memory';
+export { subjectMatches, isSubject } from './subjects';
+export { DELIVERY, START_AT, MESSAGING_LOG, LT_SUBJECTS } from './constants';