@hotmeshio/long-tail 0.25.3 → 0.26.0

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

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * The line protocol as JSON Schema plus the rules a schema cannot express.
+ * Known fields are checked; unknown fields are allowed, so a machine on a
+ * newer minor version can add fields without breaking older gateways. The
+ * gateway checks every inbound message; the tests check everything the mock sends.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectMessage = inspectMessage;
+const ajv_1 = __importDefault(require("ajv"));
+const constants_1 = require("./constants");
+const envelope_1 = require("./envelope");
+const topics_1 = require("./topics");
+const STR = { type: 'string' };
+const STR_N = { type: ['string', 'null'] };
+const NUM = { type: 'number' };
+const INT0 = { type: 'integer', minimum: 0 };
+const BOOL = { type: 'boolean' };
+const TS = { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$' };
+const TS_N = { anyOf: [TS, { type: 'null' }] };
+const UUID = { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' };
+const oneOf = (o, nullable = false) => ({ enum: nullable ? [...Object.values(o), null] : Object.values(o) });
+function shape(props, optional = []) {
+    return { type: 'object', properties: props, required: Object.keys(props).filter((k) => !optional.includes(k)) };
+}
+const ENVELOPE = shape({
+    v: { type: 'string', pattern: '^1(\\.\\d+)?$' },
+    id: UUID,
+    at: TS,
+    source: shape({ site: STR, line: STR, machine: STR, station: STR }, ['station']),
+    body: { type: 'object' },
+});
+const RECIPE = { anyOf: [shape({ id: STR, version: STR }), { type: 'null' }] };
+const BODY = {
+    [topics_1.MESSAGE_KIND.PRESENCE]: shape({ online: BOOL, software: STR }, ['software']),
+    [topics_1.MESSAGE_KIND.SNAPSHOT]: shape({
+        bootId: STR, software: STR, mode: oneOf(constants_1.MODE), enabled: BOOL, recipe: RECIPE,
+        jobs: { type: 'array', items: shape({ jobId: STR, units: { type: 'array', items: STR }, status: STR }) },
+        alarms: { type: 'array', items: STR },
+        cycles: INT0,
+    }),
+    [topics_1.MESSAGE_KIND.JOB]: shape({
+        event: oneOf(constants_1.JOB_EVENT), jobId: STR, unitId: STR, orderRef: STR, recipe: RECIPE, carrierId: STR_N, peer: STR_N,
+        result: oneOf(constants_1.JOB_RESULT), reason: STR_N,
+        measurements: {
+            type: 'array',
+            items: shape({ name: STR, value: NUM, unit: STR_N, min: { type: ['number', 'null'] }, max: { type: ['number', 'null'] }, ok: BOOL }),
+        },
+        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']),
+    [topics_1.MESSAGE_KIND.ALARM]: shape({
+        alarmId: STR, code: STR, level: oneOf(constants_1.LEVEL), text: STR, active: BOOL,
+        raisedAt: TS, clearedAt: TS_N, clearedBy: STR_N, ackedBy: STR_N, ackedAt: TS_N,
+        zone: STR_N, autoClears: BOOL, action: STR_N, jobId: STR_N,
+    }),
+    [topics_1.MESSAGE_KIND.TELEMETRY]: shape({ readings: { type: 'object', additionalProperties: NUM } }),
+    [topics_1.MESSAGE_KIND.CMD]: shape({ cmdId: STR, op: oneOf(constants_1.OP), args: { type: 'object' } }),
+    [topics_1.MESSAGE_KIND.REPLY]: shape({ cmdId: STR, status: oneOf(constants_1.REPLY_STATUS), reason: STR }),
+    [topics_1.MESSAGE_KIND.REPORT]: { type: 'object' },
+};
+const ajv = new ajv_1.default({ allErrors: true, strict: false });
+const ENVELOPE_V = ajv.compile(ENVELOPE);
+const BODY_V = Object.fromEntries(Object.entries(BODY).map(([k, s]) => [k, ajv.compile(s)]));
+const RETAINED = [topics_1.MESSAGE_KIND.PRESENCE, topics_1.MESSAGE_KIND.SNAPSHOT, topics_1.MESSAGE_KIND.ALARM];
+const errorsOf = (prefix, fn) => (fn.errors ?? []).map((e) => `${prefix}: ${e.instancePath || '.'} ${e.message}`);
+/** Validate one message. `retained` is the publisher's flag when the transport reports it. */
+function inspectMessage(root, topic, raw, retained) {
+    const parsed = (0, topics_1.parseTopic)(root, topic);
+    if (!parsed)
+        return { parsed, body: null, violations: ['unknown topic'] };
+    const violations = [];
+    const size = typeof raw === 'string' ? Buffer.byteLength(raw) : raw.length;
+    if (size > constants_1.MAX_PAYLOAD_BYTES)
+        violations.push(`payload ${size} B exceeds ${constants_1.MAX_PAYLOAD_BYTES} B`);
+    if (size === 0) {
+        if (parsed.kind !== topics_1.MESSAGE_KIND.ALARM)
+            violations.push('empty payload');
+        return { parsed, body: null, violations };
+    }
+    const body = (0, envelope_1.parsePayload)(raw);
+    if (!body)
+        return { parsed, body: null, violations: [...violations, 'not a JSON object'] };
+    if (!ENVELOPE_V(body))
+        violations.push(...errorsOf('envelope', ENVELOPE_V));
+    const bodyV = BODY_V[parsed.kind];
+    if (!bodyV(body.body ?? {}))
+        violations.push(...errorsOf(parsed.kind, bodyV));
+    violations.push(...crossFieldRules(parsed, body, retained));
+    return { parsed, body, violations };
+}
+function crossFieldRules(parsed, env, retained) {
+    const out = [];
+    const b = env.body ?? {};
+    const { ident, kind, key } = parsed;
+    const s = env.source ?? {};
+    if (s.site !== ident.siteId || s.line !== ident.lineId || s.machine !== ident.machineId)
+        out.push('source disagrees with the topic');
+    if (kind === topics_1.MESSAGE_KIND.ALARM && b.alarmId !== key)
+        out.push('alarmId disagrees with the topic');
+    if (kind === topics_1.MESSAGE_KIND.JOB) {
+        if (b.event === constants_1.JOB_EVENT.FINISHED) {
+            for (const field of ['result', 'measurements', 'materials', 'startedAt', 'endedAt']) {
+                if (!(field in b))
+                    out.push(`finished without ${field}`);
+            }
+        }
+        if (b.result && b.result !== constants_1.JOB_RESULT.OK && !b.reason)
+            out.push(`${b.result} without a reason`);
+        if (b.event === constants_1.JOB_EVENT.TRANSFER_FAILED && !b.failure)
+            out.push('transfer-failed without a failure');
+        // The schema has already reported a malformed list; these rules read only well-formed entries.
+        for (const m of Array.isArray(b.measurements) ? b.measurements : []) {
+            if (!m || typeof m !== 'object')
+                continue;
+            if (m.min != null && m.max != null && (m.min <= m.value && m.value <= m.max) !== m.ok)
+                out.push(`${m.name}: ok disagrees with min/max`);
+        }
+    }
+    if (retained === undefined)
+        return out;
+    if ((kind === topics_1.MESSAGE_KIND.PRESENCE || kind === topics_1.MESSAGE_KIND.SNAPSHOT) && !retained)
+        out.push(`${kind} not retained`);
+    if (kind === topics_1.MESSAGE_KIND.ALARM && b.active === true && !retained)
+        out.push('active alarm not retained');
+    if (!RETAINED.includes(kind) && retained)
+        out.push(`${kind} must not be retained`);
+    return out;
+}

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

@@ -0,0 +1,14 @@
+import type { Envelope, MachineIdent } from '../../../types/machines';
+export type { Envelope, MachineIdent };
+/** The machine's wire address: its topic level and client id. */
+export declare function addressOf(ident: MachineIdent): string;
+/** {site}-{line}-{address}, stable across reconnects. */
+export declare function clientIdOf(ident: MachineIdent): string;
+/** ISO 8601 UTC with milliseconds. */
+export declare function isoTs(at?: Date | number): string;
+export declare function buildEnvelope<T>(ident: MachineIdent, body: T, opts?: {
+    at?: string;
+    id?: string;
+}): Envelope<T>;
+/** Parse a JSON payload; null when it is empty or not an object. */
+export declare function parsePayload(raw: string | Buffer): Envelope | null;

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

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addressOf = addressOf;
+exports.clientIdOf = clientIdOf;
+exports.isoTs = isoTs;
+exports.buildEnvelope = buildEnvelope;
+exports.parsePayload = parsePayload;
+const crypto_1 = require("crypto");
+const constants_1 = require("./constants");
+/** The machine's wire address: its topic level and client id. */
+function addressOf(ident) {
+    return ident.address ?? ident.machineId;
+}
+/** {site}-{line}-{address}, stable across reconnects. */
+function clientIdOf(ident) {
+    return `${ident.siteId}-${ident.lineId}-${addressOf(ident)}`;
+}
+/** ISO 8601 UTC with milliseconds. */
+function isoTs(at = Date.now()) {
+    return new Date(at).toISOString();
+}
+function buildEnvelope(ident, body, opts = {}) {
+    return {
+        v: constants_1.PROTOCOL_VERSION,
+        id: opts.id ?? (0, crypto_1.randomUUID)(),
+        at: opts.at ?? isoTs(),
+        source: { site: ident.siteId, line: ident.lineId, machine: addressOf(ident), ...(ident.address && ident.address !== ident.machineId ? { station: ident.machineId } : {}) },
+        body,
+    };
+}
+/** Parse a JSON payload; null when it is empty or not an object. */
+function parsePayload(raw) {
+    const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+    if (!text)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from './constants';
+export * from './envelope';
+export * from './topics';
+export * from './contract';
+export * from './codec';

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

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./constants"), exports);
+__exportStar(require("./envelope"), exports);
+__exportStar(require("./topics"), exports);
+__exportStar(require("./contract"), exports);
+__exportStar(require("./codec"), exports);

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

@@ -0,0 +1,33 @@
+/**
+ * Topic builders and the parser that classifies an inbound topic. NATS
+ * carries an MQTT topic on the subject with `/` replaced by `.`, so no topic
+ * level may contain `.`, `/`, `+`, `#` or whitespace.
+ */
+import { type MachineIdent } from './envelope';
+export declare const MESSAGE_KIND: {
+    readonly PRESENCE: "presence";
+    readonly SNAPSHOT: "snapshot";
+    readonly JOB: "job";
+    readonly ALARM: "alarm";
+    readonly TELEMETRY: "telemetry";
+    readonly CMD: "cmd";
+    readonly REPLY: "reply";
+    readonly REPORT: "report";
+};
+export type MessageKind = typeof MESSAGE_KIND[keyof typeof MESSAGE_KIND];
+export interface ParsedTopic {
+    ident: MachineIdent;
+    kind: MessageKind;
+    /** The alarm id on alarm topics; the report name on report topics. */
+    key?: string;
+}
+export declare function isTopicLevel(value: unknown): value is string;
+export declare function assertTopicLevel(name: string, value: string): void;
+export declare function machineTopic(root: string, ident: MachineIdent, channel: string): string;
+export declare function alarmTopic(root: string, ident: MachineIdent, alarmId: string): string;
+/** Every topic on one line, for a controller subscription. */
+export declare function lineFilter(root: string, siteId: string, lineId: string): string;
+export declare function toSubject(topic: string): string;
+export declare function toTopic(subject: string): string;
+/** Classify a topic under `root`; null when it is not a machine topic. */
+export declare function parseTopic(root: string, topic: string): ParsedTopic | null;

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

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Topic builders and the parser that classifies an inbound topic. NATS
+ * carries an MQTT topic on the subject with `/` replaced by `.`, so no topic
+ * level may contain `.`, `/`, `+`, `#` or whitespace.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESSAGE_KIND = void 0;
+exports.isTopicLevel = isTopicLevel;
+exports.assertTopicLevel = assertTopicLevel;
+exports.machineTopic = machineTopic;
+exports.alarmTopic = alarmTopic;
+exports.lineFilter = lineFilter;
+exports.toSubject = toSubject;
+exports.toTopic = toTopic;
+exports.parseTopic = parseTopic;
+const constants_1 = require("./constants");
+const envelope_1 = require("./envelope");
+exports.MESSAGE_KIND = {
+    PRESENCE: 'presence',
+    SNAPSHOT: 'snapshot',
+    JOB: 'job',
+    ALARM: 'alarm',
+    TELEMETRY: 'telemetry',
+    CMD: 'cmd',
+    REPLY: 'reply',
+    REPORT: 'report',
+};
+const RESERVED = /[/+#.\s]/;
+function isTopicLevel(value) {
+    return typeof value === 'string' && !!value && !RESERVED.test(value);
+}
+function assertTopicLevel(name, value) {
+    if (!isTopicLevel(value)) {
+        throw new Error(`${name} "${value}" is not a valid topic level (no / + # . or whitespace)`);
+    }
+}
+function machineTopic(root, ident, channel) {
+    return `${root}/${ident.siteId}/${ident.lineId}/${(0, envelope_1.addressOf)(ident)}/${channel}`;
+}
+function alarmTopic(root, ident, alarmId) {
+    return machineTopic(root, ident, `${constants_1.CHANNEL.ALARM}/${alarmId}`);
+}
+/** Every topic on one line, for a controller subscription. */
+function lineFilter(root, siteId, lineId) {
+    return `${root}/${siteId}/${lineId}/#`;
+}
+function toSubject(topic) {
+    return topic.split('/').join('.');
+}
+function toTopic(subject) {
+    return subject.split('.').join('/');
+}
+const CHANNEL_KIND = {
+    [constants_1.CHANNEL.PRESENCE]: exports.MESSAGE_KIND.PRESENCE,
+    [constants_1.CHANNEL.SNAPSHOT]: exports.MESSAGE_KIND.SNAPSHOT,
+    [constants_1.CHANNEL.JOB]: exports.MESSAGE_KIND.JOB,
+    [constants_1.CHANNEL.TELEMETRY]: exports.MESSAGE_KIND.TELEMETRY,
+    [constants_1.CHANNEL.CMD]: exports.MESSAGE_KIND.CMD,
+    [constants_1.CHANNEL.REPLY]: exports.MESSAGE_KIND.REPLY,
+};
+/** Classify a topic under `root`; null when it is not a machine topic. */
+function parseTopic(root, topic) {
+    const prefix = `${root}/`;
+    if (!topic.startsWith(prefix))
+        return null;
+    const [siteId, lineId, machineId, ...rest] = topic.slice(prefix.length).split('/');
+    if (!siteId || !lineId || !machineId || rest.length === 0)
+        return null;
+    const ident = { siteId, lineId, machineId };
+    const kind = CHANNEL_KIND[rest.join('/')];
+    if (kind)
+        return { ident, kind };
+    if (rest.length === 2 && rest[0] === constants_1.CHANNEL.ALARM)
+        return { ident, kind: exports.MESSAGE_KIND.ALARM, key: rest[1] };
+    if (rest.length >= 2 && rest[0] === constants_1.CHANNEL.REPORT)
+        return { ident, kind: exports.MESSAGE_KIND.REPORT, key: rest.slice(1).join('/') };
+    return null;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The machine broker (Mosquitto), rendered from the line. Machines speak
+ * MQTT 5 to it over TLS, each with its own client certificate (the CN is
+ * its username). The ACL lets a machine publish only its own channels and
+ * read only its own commands, and lets the line controller command every
+ * machine on the line. A bridge carries the line's topics out to the site
+ * NATS, where JetStream keeps them.
+ */
+import { type LineCodec } from '../protocol/codec';
+import { type LineDef } from '../line';
+export interface MosquittoConfOptions {
+    root: string;
+    /** Certificate directory as the broker sees it. */
+    certDir: string;
+    /** Where the site NATS MQTT listener is, host:port. */
+    siteNats: string;
+    aclFile: string;
+    maxPacketBytes?: number;
+}
+export declare function renderMosquittoConf(line: LineDef, opts: MosquittoConfOptions): string;
+/**
+ * The codec's channels decide the topics: a machine writes its events and telemetry and reads its commands.
+ * A station whose address the line learns has no user of its own: `pattern` rules give every certificate
+ * the channels under its own name (%u), so its certificate's common name must be its address. On a line
+ * that also declares addresses, a certificate named for a declared address is denied that station's channels.
+ */
+export declare function renderMosquittoAcl(line: LineDef, codec: Pick<LineCodec, 'root' | 'channels' | 'topicFor'>): string;

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

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * The machine broker (Mosquitto), rendered from the line. Machines speak
+ * MQTT 5 to it over TLS, each with its own client certificate (the CN is
+ * its username). The ACL lets a machine publish only its own channels and
+ * read only its own commands, and lets the line controller command every
+ * machine on the line. A bridge carries the line's topics out to the site
+ * NATS, where JetStream keeps them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMosquittoConf = renderMosquittoConf;
+exports.renderMosquittoAcl = renderMosquittoAcl;
+const envelope_1 = require("../protocol/envelope");
+const codec_1 = require("../protocol/codec");
+const line_1 = require("../line");
+const site_conf_1 = require("./site-conf");
+function renderMosquittoConf(line, opts) {
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
+persistence true
+persistence_location /mosquitto/data/
+log_dest stdout
+log_type error
+log_type warning
+log_type notice
+
+listener 8883
+cafile ${opts.certDir}/ca.pem
+certfile ${opts.certDir}/broker.pem
+keyfile ${opts.certDir}/broker.key
+require_certificate true
+use_identity_as_username true
+acl_file ${opts.aclFile}
+max_packet_size ${opts.maxPacketBytes ?? 262_144}
+
+connection ${line.siteId}-${line.lineId}-site-nats
+address ${opts.siteNats}
+bridge_protocol_version mqttv311
+bridge_cafile ${opts.certDir}/ca.pem
+bridge_certfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.pem
+bridge_keyfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.key
+remote_clientid ${(0, site_conf_1.bridgeId)(line)}
+cleansession false
+try_private false
+notifications false
+topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
+`;
+}
+/**
+ * The codec's channels decide the topics: a machine writes its events and telemetry and reads its commands.
+ * A station whose address the line learns has no user of its own: `pattern` rules give every certificate
+ * the channels under its own name (%u), so its certificate's common name must be its address. On a line
+ * that also declares addresses, a certificate named for a declared address is denied that station's channels.
+ */
+function renderMosquittoAcl(line, codec) {
+    const { siteId, lineId } = line;
+    const { events, telemetry, commands } = codec.channels;
+    const own = (address, channels) => channels.map((c) => (0, codec_1.topicOf)(codec, { siteId, lineId, address }, c));
+    const rules = (prefix, address) => [
+        ...own(address, [...events, ...telemetry]).map((t) => `${prefix}write ${t}`),
+        ...own(address, commands).map((t) => `${prefix}read ${t}`),
+    ];
+    const declared = line.machines.filter((m) => !(0, line_1.learnsAddress)(line, m.machineId)).map((m) => (0, line_1.identOf)(line, m.machineId));
+    const machines = declared.map((ident) => [`user ${(0, envelope_1.clientIdOf)(ident)}`, ...rules('topic ', (0, envelope_1.addressOf)(ident))].join('\n'));
+    const learns = line.machines.some((m) => (0, line_1.learnsAddress)(line, m.machineId));
+    const learned = learns ? [['# Stations that learn their address: each certificate, under its own common name.', ...rules('pattern ', '%u')].join('\n')] : [];
+    const every = [...events, ...telemetry, ...commands];
+    const shadows = learns ? declared.map((ident) => shadowRules(line, (0, envelope_1.addressOf)(ident), own((0, envelope_1.addressOf)(ident), every))) : [];
+    const controller = [
+        `user ${(0, line_1.controllerId)(line)}`,
+        ...commands.map((c) => `topic write ${(0, codec_1.topicOf)(codec, { siteId, lineId }, c)}`),
+        `topic read ${codec.root}/${siteId}/${lineId}/#`,
+    ].join('\n');
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${[...learned, ...shadows, ...machines, controller].join('\n\n')}\n`;
+}
+/** Deny a declared station's channels to a certificate named for its address, which the patterns would grant. */
+function shadowRules(line, address, topics) {
+    const users = [(0, line_1.controllerId)(line), ...line.machines.filter((m) => !(0, line_1.learnsAddress)(line, m.machineId)).map((m) => (0, envelope_1.clientIdOf)((0, line_1.identOf)(line, m.machineId)))];
+    if (users.includes(address))
+        throw new Error(`address "${address}" is also a broker user name; a declared address on a learning line must differ from every user`);
+    return [`user ${address}`, ...topics.map((t) => `topic deny ${t}`)].join('\n');
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+import type { LineDef } from '../line';
+export interface SiteConfOptions {
+    root: string;
+    gatewayUser: string;
+    gatewayPassword: string;
+    certDir: string;
+    storeDir: string;
+    mqttPort?: number;
+}
+/** The machine broker's bridge identity for a line. */
+export declare function bridgeId(line: LineDef): string;
+export declare function renderSiteConf(line: LineDef, opts: SiteConfOptions): string;

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

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridgeId = bridgeId;
+exports.renderSiteConf = renderSiteConf;
+const protocol_1 = require("../protocol");
+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.>'];
+function renderSiteConf(line, opts) {
+    const base = (0, protocol_1.toSubject)(`${opts.root}/${line.siteId}/${line.lineId}`);
+    const bridge = [
+        `    { user: ${q(`CN=${bridgeId(line)}`)}, allowed_connection_types: ["MQTT"],`,
+        `      permissions: { publish: [${q(`${base}.>`)}], subscribe: { deny: [">"] } } }`,
+    ].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}.>`])} } }`,
+    ].join('\n');
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
+server_name: ${q(`${line.siteId}-${line.lineId}`)}
+port: 4222
+http: 8222
+jetstream { store_dir: ${q(opts.storeDir)} }
+
+authorization {
+  users: [
+${bridge}
+${gateway}
+  ]
+}
+
+mqtt {
+  port: ${opts.mqttPort ?? 8883}
+  tls {
+    cert_file: ${q(`${opts.certDir}/server.pem`)}
+    key_file: ${q(`${opts.certDir}/server.key`)}
+    ca_file: ${q(`${opts.certDir}/ca.pem`)}
+    verify_and_map: true
+    timeout: 5
+  }
+}
+`;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Escalation events from Long Tail's in-process event adapter. With a
+ * cross-container bus configured, the adapter also receives events other
+ * containers publish. Nothing is replayed: the gateway reconciles open rows
+ * when it starts leading a line.
+ */
+import type { CallbackEventAdapter } from '../../events/callback';
+import { type EscalationEvent, type EscalationFeed } from './delivery';
+import type { MachineDisposition } from '../../../types/machines';
+export declare class CallbackEscalationFeed implements EscalationFeed {
+    private readonly adapter;
+    private off?;
+    private readonly redelivery;
+    constructor(adapter: CallbackEventAdapter, nakDelayMs?: number);
+    connect(): Promise<void>;
+    consume(handler: (event: EscalationEvent) => Promise<MachineDisposition>): Promise<void>;
+    close(): Promise<void>;
+}

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

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Escalation events from Long Tail's in-process event adapter. With a
+ * cross-container bus configured, the adapter also receives events other
+ * containers publish. Nothing is replayed: the gateway reconciles open rows
+ * when it starts leading a line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallbackEscalationFeed = void 0;
+const delivery_1 = require("./delivery");
+const serial_1 = require("./serial");
+const ESCALATION_EVENTS = 'system.escalation.>';
+class CallbackEscalationFeed {
+    constructor(adapter, nakDelayMs = 1_000) {
+        this.adapter = adapter;
+        this.redelivery = new serial_1.LocalRedelivery(new serial_1.SerialQueue(), nakDelayMs);
+    }
+    async connect() { }
+    async consume(handler) {
+        this.off = this.adapter.on(ESCALATION_EVENTS, (raw) => {
+            const event = (0, delivery_1.toEscalationEvent)(raw);
+            if (event)
+                void this.redelivery.deliver(() => handler(event));
+        });
+    }
+    async close() {
+        this.off?.();
+        await this.redelivery.stop();
+    }
+}
+exports.CallbackEscalationFeed = CallbackEscalationFeed;

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

@@ -0,0 +1,21 @@
+/**
+ * Two sides of the machine fabric. A machine holds a MachineLink: one MQTT
+ * client with a will, publishing under its own subtree and hearing only its
+ * 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 { EscalationEvent, EscalationFeed, InboundMessage, LinkConnectOptions, LinkWill, MachineBus, MachineLink, PublishOptions } from '../../../types/machines';
+export type { EscalationEvent, EscalationFeed, InboundMessage, LinkConnectOptions, LinkWill, MachineBus, MachineLink, PublishOptions };
+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];
+/** 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. */
+export declare function toEscalationEvent(body: Record<string, any>): EscalationEvent | null;

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

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Two sides of the machine fabric. A machine holds a MachineLink: one MQTT
+ * client with a will, publishing under its own subtree and hearing only its
+ * own commands. The gateway holds a MachineBus: durable, ordered delivery of
+ * every machine message on the line, QoS 1 command egress, and retained reads.
+ */
+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',
+};
+/** MQTT filter match with `+` (one level) and `#` (the rest). */
+function topicMatches(filter, topic) {
+    const f = filter.split('/');
+    const t = topic.split('/');
+    for (let i = 0; i < f.length; i++) {
+        if (f[i] === '#')
+            return true;
+        if (i >= t.length)
+            return false;
+        if (f[i] !== '+' && f[i] !== t[i])
+            return false;
+    }
+    return f.length === t.length;
+}
+const ESCALATION_SUBJECT = /^(?:.*\.)?system\.escalation\.([^.]+)\.([^.]+)\.([^.]+)$/;
+/** Read an LTEvent body into an EscalationEvent; null for other families. */
+function toEscalationEvent(body) {
+    const match = typeof body?.type === 'string' ? ESCALATION_SUBJECT.exec(body.type) : null;
+    if (!match)
+        return null;
+    const [, role, escalationId, verb] = match;
+    return { type: body.type, escalationId: body.escalationId ?? escalationId, role: body.role ?? role, verb, data: body.data ?? {} };
+}

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

@@ -0,0 +1,11 @@
+export * from './delivery';
+export * from './memory-broker';
+export * from './memory';
+export * from './serial';
+export * from './streams';
+export * from './mqtt-session';
+export * from './mqtt-link';
+export * from './mqtt-bus';
+export * from './nats-bus';
+export * from './nats-feed';
+export * from './callback-feed';