@hotmeshio/long-tail 0.26.0 → 0.27.0

package/build/index.d.ts

@@ -21,6 +21,10 @@ export { NatsEventAdapter } from './lib/events/nats';
 export { InMemoryEventAdapter } from './lib/events/memory';
 export { SocketIOEventAdapter, type SocketIOAuthenticator } from './lib/events/socketio';
 export { publishMilestoneEvent, publishTaskEvent, publishEscalationEvent, publishActivityEvent, publishWorkflowEvent, publishAgentEvent, publishKnowledgeEvent } from './lib/events/publish';
+export { messagingRegistry, MemoryMessagingProvider, DELIVERY } from './lib/messaging';
+export { NatsMessagingProvider } from './lib/messaging/nats/provider';
+export { renderNatsConf, type NatsConfOptions, type EdgeAccount, type NatsUser } from './lib/messaging/nats/render-conf';
+export { jsPermissions } from './lib/messaging/nats/permissions';
 export { telemetryRegistry } from './lib/telemetry';
 export { HoneycombTelemetryAdapter } from './lib/telemetry/honeycomb';
 export { loggerRegistry } from './lib/logger';

package/build/index.js

@@ -15,9 +15,6 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 var __importStar = (this && this.__importStar) || (function () {
     var ownKeys = function(o) {
         ownKeys = Object.getOwnPropertyNames || function (o) {
@@ -35,12 +32,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
-exports.LTExpressAdapter = exports.Machines = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = void 0;
+exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.jsPermissions = exports.renderNatsConf = exports.NatsMessagingProvider = exports.DELIVERY = exports.MemoryMessagingProvider = exports.messagingRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
+exports.LTExpressAdapter = exports.Machines = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
+const path = __importStar(require("path"));
 const start_1 = require("./start");
 const line_1 = require("./lib/machines/line");
 // ─── Package Exports ─────────────────────────────────────────────────────────
@@ -100,6 +101,16 @@ Object.defineProperty(exports, "publishActivityEvent", { enumerable: true, get:
 Object.defineProperty(exports, "publishWorkflowEvent", { enumerable: true, get: function () { return publish_1.publishWorkflowEvent; } });
 Object.defineProperty(exports, "publishAgentEvent", { enumerable: true, get: function () { return publish_1.publishAgentEvent; } });
 Object.defineProperty(exports, "publishKnowledgeEvent", { enumerable: true, get: function () { return publish_1.publishKnowledgeEvent; } });
+var messaging_1 = require("./lib/messaging");
+Object.defineProperty(exports, "messagingRegistry", { enumerable: true, get: function () { return messaging_1.messagingRegistry; } });
+Object.defineProperty(exports, "MemoryMessagingProvider", { enumerable: true, get: function () { return messaging_1.MemoryMessagingProvider; } });
+Object.defineProperty(exports, "DELIVERY", { enumerable: true, get: function () { return messaging_1.DELIVERY; } });
+var provider_1 = require("./lib/messaging/nats/provider");
+Object.defineProperty(exports, "NatsMessagingProvider", { enumerable: true, get: function () { return provider_1.NatsMessagingProvider; } });
+var render_conf_1 = require("./lib/messaging/nats/render-conf");
+Object.defineProperty(exports, "renderNatsConf", { enumerable: true, get: function () { return render_conf_1.renderNatsConf; } });
+var permissions_1 = require("./lib/messaging/nats/permissions");
+Object.defineProperty(exports, "jsPermissions", { enumerable: true, get: function () { return permissions_1.jsPermissions; } });
 var telemetry_1 = require("./lib/telemetry");
 Object.defineProperty(exports, "telemetryRegistry", { enumerable: true, get: function () { return telemetry_1.telemetryRegistry; } });
 var honeycomb_1 = require("./lib/telemetry/honeycomb");
@@ -257,7 +268,7 @@ async function main() {
         // Machines resolve rows over MQTT when a line and a transport are configured
         // (docker-compose.machines.yml sets both).
         machines: process.env.MACHINE_TRANSPORT && process.env.MACHINE_LINE_CONFIG
-            ? { lines: [(0, line_1.loadLine)(process.env.MACHINE_LINE_CONFIG)] }
+            ? machinesFromEnv(process.env.MACHINE_LINE_CONFIG, process.env.MACHINE_CODEC_MODULE)
             : undefined,
         branding: {
             ...(process.env.WHITE_LABEL ? { appName: process.env.WHITE_LABEL } : {}),
@@ -266,11 +277,22 @@ async function main() {
             themes: [midnight_1.midnightTheme],
         },
         telemetry: honeycombKey ? { honeycomb: { apiKey: honeycombKey } } : undefined,
-        events: config_1.config.EVENT_TRANSPORT === 'nats'
-            ? { nats: { url: config_1.config.NATS_URL, wsUrl: config_1.config.NATS_WS_URL || undefined, token: config_1.config.NATS_TOKEN || undefined } }
+        // Messaging from LT_MESSAGING / LT_NATS_* when set; otherwise the older EVENT_TRANSPORT=nats with NATS_*.
+        messaging: !process.env.LT_MESSAGING && config_1.config.EVENT_TRANSPORT === 'nats'
+            ? { nats: { url: config_1.config.NATS_URL, token: config_1.config.NATS_TOKEN || undefined, ws: { url: config_1.config.NATS_WS_URL || undefined } } }
             : undefined,
     });
 }
+/** The configured line, spoken to by the codec MACHINE_CODEC_MODULE names (its `createCodec(line)`), or the generic one. */
+function machinesFromEnv(lineConfig, codecModule) {
+    const line = (0, line_1.loadLine)(lineConfig);
+    if (!codecModule)
+        return { lines: [line] };
+    const { createCodec } = require(path.resolve(codecModule));
+    if (typeof createCodec !== 'function')
+        throw new Error(`MACHINE_CODEC_MODULE=${codecModule} exports no createCodec(line)`);
+    return { lines: [line], codec: createCodec(line) };
+}
 // Run server when executed directly
 if (require.main === module) {
     require('dotenv').config();

package/build/lib/events/nats.d.ts

@@ -1,4 +1,7 @@
 import type { LTEvent, LTEventAdapter } from '../../types';
+import type { LTMessagingProvider } from '../../types/messaging';
+/** The part of Long Tail's messaging the adapter uses. */
+export type EventMessaging = Pick<LTMessagingProvider, 'connected' | 'pubsub'>;
 /**
  * NATS event adapter — publish AND subscribe.
  *
@@ -11,6 +14,9 @@ import type { LTEvent, LTEventAdapter } from '../../types';
  * An `_originId` field prevents the publishing container from
  * re-dispatching its own events.
  *
+ * Given `messaging` (Long Tail's messaging, `start({ messaging })`), it publishes
+ * and bridges over that connection; otherwise it opens a connection of its own.
+ *
  * Usage:
  * ```typescript
  * import { eventRegistry, NatsEventAdapter } from '@hotmeshio/long-tail';
@@ -22,6 +28,8 @@ import type { LTEvent, LTEventAdapter } from '../../types';
 export declare class NatsEventAdapter implements LTEventAdapter {
     private nc;
     private sub;
+    private readonly messaging;
+    private bridge;
     private url;
     private _wsUrl;
     private _wsProxyTarget;
@@ -36,6 +44,7 @@ export declare class NatsEventAdapter implements LTEventAdapter {
         wsProxy?: string;
         subjectPrefix?: string;
         token?: string;
+        messaging?: EventMessaging;
     });
     /**
      * Public NATS WebSocket URL for browser connections.
@@ -59,6 +68,8 @@ export declare class NatsEventAdapter implements LTEventAdapter {
      */
     setCallbackBridge(adapter: LTEventAdapter): void;
     connect(): Promise<void>;
+    /** An event from another container, handed to the local callback adapter. */
+    private bridgeIn;
     publish(event: LTEvent): Promise<void>;
     disconnect(): Promise<void>;
 }

package/build/lib/events/nats.js

@@ -18,6 +18,9 @@ const sc = (0, nats_1.StringCodec)();
  * An `_originId` field prevents the publishing container from
  * re-dispatching its own events.
  *
+ * Given `messaging` (Long Tail's messaging, `start({ messaging })`), it publishes
+ * and bridges over that connection; otherwise it opens a connection of its own.
+ *
  * Usage:
  * ```typescript
  * import { eventRegistry, NatsEventAdapter } from '@hotmeshio/long-tail';
@@ -30,9 +33,11 @@ class NatsEventAdapter {
     constructor(options) {
         this.nc = null;
         this.sub = null;
+        this.bridge = null;
         this._wsProxyBasePath = '';
         this.originId = (0, crypto_1.randomUUID)();
         this.callbackAdapter = null;
+        this.messaging = options?.messaging ?? null;
         this.url = options?.url || config_1.config.NATS_URL;
         this._wsUrl = options?.wsUrl || config_1.config.NATS_WS_URL || null;
         this._wsProxyTarget = options?.wsProxy || null;
@@ -75,6 +80,11 @@ class NatsEventAdapter {
         this.callbackAdapter = adapter;
     }
     async connect() {
+        if (this.messaging) {
+            if (this.callbackAdapter)
+                this.bridge = this.messaging.pubsub.subscribe(`${this.subjectPrefix}.>`, (m) => this.bridgeIn(m));
+            return;
+        }
         this.nc = await (0, nats_1.connect)({
             servers: this.url,
             token: this.token,
@@ -102,15 +112,36 @@ class NatsEventAdapter {
             })();
         }
     }
+    /** An event from another container, handed to the local callback adapter. */
+    bridgeIn(m) {
+        try {
+            const event = JSON.parse(m.payload);
+            if (event._originId === this.originId)
+                return;
+            this.callbackAdapter?.publish(event);
+        }
+        catch {
+            // Malformed message, skip
+        }
+    }
     async publish(event) {
-        if (!this.nc)
-            return;
         const subject = `${this.subjectPrefix}.${event.type}`;
         const enriched = { ...event, _originId: this.originId };
+        if (this.messaging) {
+            if (this.messaging.connected)
+                await this.messaging.pubsub.publish(subject, JSON.stringify(enriched));
+            return;
+        }
+        if (!this.nc)
+            return;
         this.nc.publish(subject, sc.encode(JSON.stringify(enriched)));
         logger_1.loggerRegistry.info(`[lt-events:nats] published: ${subject} (origin=${this.originId.slice(0, 8)})`);
     }
     async disconnect() {
+        if (this.bridge) {
+            await this.bridge.close();
+            this.bridge = null;
+        }
         if (this.sub) {
             this.sub.unsubscribe();
             this.sub = null;

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

@@ -2,4 +2,5 @@ export * from './protocol';
 export * from './transport';
 export * from './line';
 export * from './site/site-conf';
+export * from './site/edge-account';
 export * from './site/mosquitto-conf';

package/build/lib/machines/index.js

@@ -18,4 +18,5 @@ __exportStar(require("./protocol"), exports);
 __exportStar(require("./transport"), exports);
 __exportStar(require("./line"), exports);
 __exportStar(require("./site/site-conf"), exports);
+__exportStar(require("./site/edge-account"), exports);
 __exportStar(require("./site/mosquitto-conf"), exports);

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

@@ -16,6 +16,10 @@ export interface MachineCommand {
     cmdId: string;
     op: string;
     args: Record<string, unknown>;
+    /** How many times this gateway has sent this cmdId, this time included. */
+    attempt?: number;
+    /** The command may have reached the machine before: sent earlier, or its row predates this gateway's takeover. */
+    retry?: boolean;
 }
 /** MQTT filters under each machine's topic, e.g. `job` or `alarm/+`. */
 export interface CodecChannels {
@@ -55,6 +59,18 @@ export interface LineCodec {
      * to a person. Otherwise (the default) known fields are acted on and the violations are logged.
      */
     readonly strict?: boolean;
+    /**
+     * The machines keep no retained state and report only what changes: the gateway asks each one for
+     * a snapshot when it takes the line, so it knows every machine's job before acting on a change.
+     */
+    readonly snapshotOnStart?: boolean;
+    /**
+     * Active alarms stay retained on the broker until they clear, as in the line protocol. A takeover's
+     * retained read is then every active alarm, and an alarm row whose alarm is missing from it cleared
+     * while no gateway listened. Otherwise a machine's snapshot lists its active alarms, and an alarm it
+     * no longer lists has cleared.
+     */
+    readonly retainedAlarms?: boolean;
     /** One wire message as zero or more line-protocol messages; empty when the topic is not a machine's. */
     decode(topic: string, payload: string, retained?: boolean): Inspection[];
     /** The command as wire messages; none when the machines have no such command, and the gateway then sends nothing. */

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

@@ -66,6 +66,7 @@ function genericCodec(opts) {
         channels: exports.GENERIC_CHANNELS,
         unitsPerDispatch: opts.unitsPerDispatch ?? null,
         dispatchOn: opts.dispatchOn ?? exports.DISPATCH_ON.CREATED,
+        retainedAlarms: true,
         decode(topic, payload, retained) {
             const seen = atMachine((0, contract_1.inspectMessage)(opts.root, topic, payload, retained), ids);
             if (!seen.parsed)

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

@@ -51,7 +51,8 @@ const BODY = {
         },
         materials: { type: 'array', items: shape({ material: STR, lot: STR }) },
         startedAt: TS, endedAt: TS, durationMs: INT0, failure: oneOf(constants_1.TRANSFER_FAILURE),
-    }, ['peer', 'result', 'reason', 'measurements', 'materials', 'startedAt', 'endedAt', 'durationMs', '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']),
     [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,
@@ -92,6 +93,8 @@ function inspectMessage(root, topic, raw, retained) {
     violations.push(...crossFieldRules(parsed, body, retained));
     return { parsed, body, violations };
 }
+/** 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];
 function crossFieldRules(parsed, env, retained) {
     const out = [];
     const b = env.body ?? {};
@@ -102,6 +105,12 @@ 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';
+        if (b.unitId === undefined && !byCarrier)
+            out.push(`${b.event} without a unitId`);
+        if (b.jobId === undefined && !byCarrier)
+            out.push(`${b.event} without a jobId`);
         if (b.event === constants_1.JOB_EVENT.FINISHED) {
             for (const field of ['result', 'measurements', 'materials', 'startedAt', 'endedAt']) {
                 if (!(field in b))

package/build/lib/machines/site/edge-account.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A line's edge account on Long Tail's NATS: the machine broker's bridge logs
+ * in by client certificate (the CN is its user), over MQTT only, and may
+ * publish under the line's topics and subscribe to nothing. Long Tail imports
+ * exactly those subjects.
+ */
+import type { EdgeAccount } from '../../messaging/nats/render-conf';
+import type { LineDef } from '../line';
+/** An account name for a line: letters, digits, `-` and `_`. */
+export declare function edgeAccountName(line: LineDef): string;
+export declare function edgeAccountFor(line: LineDef, root: string, bridgeUser?: string): EdgeAccount;

package/build/lib/machines/site/edge-account.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * A line's edge account on Long Tail's NATS: the machine broker's bridge logs
+ * in by client certificate (the CN is its user), over MQTT only, and may
+ * publish under the line's topics and subscribe to nothing. Long Tail imports
+ * exactly those subjects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.edgeAccountName = edgeAccountName;
+exports.edgeAccountFor = edgeAccountFor;
+const protocol_1 = require("../protocol");
+const site_conf_1 = require("./site-conf");
+/** An account name for a line: letters, digits, `-` and `_`. */
+function edgeAccountName(line) {
+    return `EDGE_${line.siteId}_${line.lineId}`.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+function edgeAccountFor(line, root, bridgeUser = `CN=${(0, site_conf_1.bridgeId)(line)}`) {
+    const subjects = `${(0, protocol_1.toSubject)(`${root}/${line.siteId}/${line.lineId}`)}.>`;
+    return {
+        name: edgeAccountName(line),
+        subjects,
+        users: [{ user: bridgeUser, allowed_connection_types: ['MQTT'], permissions: { publish: [subjects], subscribe: { deny: ['>'] } } }],
+    };
+}

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

@@ -2,11 +2,12 @@
  * The site's NATS server, rendered from the line. 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 read: the JetStream
- * API, acks and its inbox, and the line's subjects. The site NATS stands
- * alone; Long Tail's escalation events stay inside Long Tail.
+ * topics). The gateway logs in by password and may only keep and read the
+ * line's streams through its own consumer (it can neither publish a machine
+ * subject nor delete a stream), and subscribe to its inbox and the line. The
+ * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
  */
-import type { LineDef } from '../line';
+import { type LineDef } from '../line';
 export interface SiteConfOptions {
     root: string;
     gatewayUser: string;
@@ -17,4 +18,6 @@ export interface SiteConfOptions {
 }
 /** The machine broker's bridge identity for a line. */
 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;

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

@@ -3,21 +3,28 @@
  * The site's NATS server, rendered from the line. 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 read: the JetStream
- * API, acks and its inbox, and the line's subjects. The site NATS stands
- * alone; Long Tail's escalation events stay inside Long Tail.
+ * topics). The gateway logs in by password and may only keep and read the
+ * line's streams through its own consumer (it can neither publish a machine
+ * subject nor delete a stream), and subscribe to its inbox and the line. The
+ * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bridgeId = bridgeId;
+exports.gatewayPublish = gatewayPublish;
 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");
 const q = JSON.stringify;
 /** The machine broker's bridge identity for a line. */
 function bridgeId(line) {
     return `${line.siteId}-${line.lineId}-bridge`;
 }
-/** What the gateway may publish: JetStream requests, acks and flow control, never a machine subject. */
-const GATEWAY_PUBLISH = ['$JS.API.>', '$JS.ACK.>', '$JS.FC.>'];
+/** What the gateway may publish: its streams' and its consumer's JetStream requests and acks, never a machine subject. */
+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 = [
@@ -26,7 +33,7 @@ function renderSiteConf(line, opts) {
     ].join('\n');
     const gateway = [
         `    { user: ${q(opts.gatewayUser)}, password: ${q(opts.gatewayPassword)}, allowed_connection_types: ["STANDARD"],`,
-        `      permissions: { publish: ${q(GATEWAY_PUBLISH)}, subscribe: ${q(['_INBOX.>', `${base}.>`])} } }`,
+        `      permissions: { publish: ${q(gatewayPublish(line))}, subscribe: ${q(['_INBOX.>', `${base}.>`])} } }`,
     ].join('\n');
     return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
 server_name: ${q(`${line.siteId}-${line.lineId}`)}

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

@@ -4,17 +4,16 @@
  * own commands. The gateway holds a MachineBus: durable, ordered delivery of
  * every machine message on the line, QoS 1 command egress, and retained reads.
  */
+import type { Delivery } from '../../../types/messaging';
 import type { EscalationEvent, EscalationFeed, InboundMessage, LinkConnectOptions, LinkWill, MachineBus, MachineLink, PublishOptions } from '../../../types/machines';
 export type { EscalationEvent, EscalationFeed, InboundMessage, LinkConnectOptions, LinkWill, MachineBus, MachineLink, PublishOptions };
+/** What the gateway does with a machine message: the messaging capability's deliveries (nak: its row does not exist yet). */
 export declare const DISPOSITION: {
-    /** Handled; do not deliver again. */
     readonly ACK: "ack";
-    /** Not yet actionable (its row does not exist yet); deliver again later. */
     readonly NAK: "nak";
-    /** Never actionable; drop it. */
     readonly TERM: "term";
 };
-export type Disposition = typeof DISPOSITION[keyof typeof DISPOSITION];
+export type Disposition = Delivery;
 /** MQTT filter match with `+` (one level) and `#` (the rest). */
 export declare function topicMatches(filter: string, topic: string): boolean;
 /** Read an LTEvent body into an EscalationEvent; null for other families. */

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

@@ -9,14 +9,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DISPOSITION = void 0;
 exports.topicMatches = topicMatches;
 exports.toEscalationEvent = toEscalationEvent;
-exports.DISPOSITION = {
-    /** Handled; do not deliver again. */
-    ACK: 'ack',
-    /** Not yet actionable (its row does not exist yet); deliver again later. */
-    NAK: 'nak',
-    /** Never actionable; drop it. */
-    TERM: 'term',
-};
+const constants_1 = require("../../messaging/constants");
+/** What the gateway does with a machine message: the messaging capability's deliveries (nak: its row does not exist yet). */
+exports.DISPOSITION = constants_1.DELIVERY;
 /** MQTT filter match with `+` (one level) and `#` (the rest). */
 function topicMatches(filter, topic) {
     const f = filter.split('/');

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

@@ -6,6 +6,8 @@ export * from './streams';
 export * from './mqtt-session';
 export * from './mqtt-link';
 export * from './mqtt-bus';
+export * from './stream-bus';
 export * from './nats-bus';
 export * from './nats-feed';
+export * from './pubsub-feed';
 export * from './callback-feed';

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

@@ -22,6 +22,8 @@ __exportStar(require("./streams"), exports);
 __exportStar(require("./mqtt-session"), exports);
 __exportStar(require("./mqtt-link"), exports);
 __exportStar(require("./mqtt-bus"), exports);
+__exportStar(require("./stream-bus"), exports);
 __exportStar(require("./nats-bus"), exports);
 __exportStar(require("./nats-feed"), exports);
+__exportStar(require("./pubsub-feed"), exports);
 __exportStar(require("./callback-feed"), exports);

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

@@ -1,12 +1,10 @@
 /**
- * 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.
  */
 import type { MqttEndpoint } from '../../../services/machines/config';
-import { type StreamCodec } from './streams';
+import type { StreamCodec } from './streams';
 import type { Disposition, InboundMessage, MachineBus } from './delivery';
 export interface NatsBusOptions {
     natsUrl: string;
@@ -23,11 +21,8 @@ export interface NatsBusOptions {
 }
 export declare class NatsMachineBus implements MachineBus {
     private readonly opts;
-    private nc?;
-    private session?;
-    private messages?;
-    private telemetry;
-    private readonly queue;
+    private readonly provider;
+    private bus?;
     constructor(opts: NatsBusOptions);
     get durableName(): string;
     connect(): Promise<void>;
@@ -37,6 +32,5 @@ export declare class NatsMachineBus implements MachineBus {
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
     close(): Promise<void>;
-    private nats;
-    private mqtt;
+    private stream;
 }

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

@@ -1,67 +1,47 @@
 "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();
+        await this.bus?.close();
+        await this.provider.disconnect();
     }
-    nats() {
-        if (!this.nc)
+    stream() {
+        if (!this.bus)
             throw new Error('NATS bus used before connect()');
-        return this.nc;
-    }
-    mqtt() {
-        if (!this.session)
-            throw new Error('NATS bus used before connect()');
-        return this.session;
+        return this.bus;
     }
 }
 exports.NatsMachineBus = NatsMachineBus;

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,7 +34,7 @@ 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));
             },