@hotmeshio/long-tail 0.25.4 → 0.27.0

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

@@ -0,0 +1,120 @@
+/**
+ * The line protocol: how a machine on an automated line talks to the line
+ * controller over MQTT. Each machine publishes under its own subtree and
+ * hears only its own commands. Every message is a small JSON envelope.
+ *
+ *   {root}/{site}/{line}/{machine}/presence     retained; birth and will, with the software version
+ *   {root}/{site}/{line}/{machine}/snapshot     retained; full machine state and its boot id
+ *   {root}/{site}/{line}/{machine}/job          job lifecycle and unit handoff
+ *   {root}/{site}/{line}/{machine}/alarm/{id}   retained while active
+ *   {root}/{site}/{line}/{machine}/telemetry    best effort readings
+ *   {root}/{site}/{line}/{machine}/cmd          controller to machine
+ *   {root}/{site}/{line}/{machine}/cmd/reply    machine to controller
+ */
+export declare const PROTOCOL_VERSION = "1";
+export declare const QOS: {
+    readonly BEST_EFFORT: 0;
+    readonly RELIABLE: 1;
+};
+/** A command with no reply inside this window counts as refused. */
+export declare const REPLY_DEADLINE_MS = 5000;
+export declare const MAX_PAYLOAD_BYTES: number;
+export declare const PRESENCE_HEARTBEAT_SEC = 30;
+export declare const SNAPSHOT_HEARTBEAT_SEC = 60;
+export declare const CHANNEL: {
+    readonly PRESENCE: "presence";
+    readonly SNAPSHOT: "snapshot";
+    readonly JOB: "job";
+    readonly ALARM: "alarm";
+    readonly TELEMETRY: "telemetry";
+    readonly CMD: "cmd";
+    readonly REPLY: "cmd/reply";
+    /** report/<name>: production, availability, inventory and other reporting, kept in the event stream. */
+    readonly REPORT: "report";
+};
+export declare const MODE: {
+    readonly IDLE: "idle";
+    readonly RUNNING: "running";
+    readonly CHANGEOVER: "changeover";
+    readonly FAULTED: "faulted";
+    readonly EMERGENCY_STOP: "emergency-stop";
+    readonly MAINTENANCE: "maintenance";
+};
+export type Mode = typeof MODE[keyof typeof MODE];
+export declare const PRODUCTIVE_MODES: readonly Mode[];
+export declare const LEVEL: {
+    readonly INFO: "info";
+    readonly WARNING: "warning";
+    readonly CRITICAL: "critical";
+    readonly EMERGENCY: "emergency";
+};
+export type Level = typeof LEVEL[keyof typeof LEVEL];
+/** Levels that stop work and need a person. */
+export declare const STOPPING_LEVELS: readonly Level[];
+/**
+ * Job events, one per unit: a job carries one or more units through a
+ * machine together. A unit moves between machines in a handshake: the
+ * receiver says READY, the sender says RELEASED, the receiver confirms
+ * ARRIVED. ARRIVED is the receipt that ends a handoff. WITHDRAWN means the
+ * job left the queue, by a cancel or by the machine giving it up.
+ */
+export declare const JOB_EVENT: {
+    readonly QUEUED: "queued";
+    readonly READY: "ready";
+    readonly ARRIVED: "arrived";
+    /** The receiver put the unit on its carrier; some machines report this instead of an arrival. */
+    readonly BOUND: "bound";
+    readonly STARTED: "started";
+    readonly PROGRESS: "progress";
+    readonly FINISHED: "finished";
+    readonly RELEASED: "released";
+    readonly TRANSFER_FAILED: "transfer-failed";
+    readonly WITHDRAWN: "withdrawn";
+};
+export type JobEvent = typeof JOB_EVENT[keyof typeof JOB_EVENT];
+export declare const JOB_RESULT: {
+    readonly OK: "ok";
+    readonly REJECT: "reject";
+    readonly HOLD: "hold";
+    readonly SCRAP: "scrap";
+    readonly REWORK: "rework";
+};
+export type JobResult = typeof JOB_RESULT[keyof typeof JOB_RESULT];
+export declare const TRANSFER_FAILURE: {
+    readonly JAM: "jam";
+    readonly INCOMPLETE_HANDSHAKE: "incomplete-handshake";
+    readonly CARRIER_MISMATCH: "carrier-mismatch";
+    readonly UNREADABLE_ID: "unreadable-id";
+};
+export type TransferFailure = typeof TRANSFER_FAILURE[keyof typeof TRANSFER_FAILURE];
+/** Commands. Every command carries a cmdId; a repeated cmdId is answered, never run twice. */
+export declare const OP: {
+    readonly DISPATCH: "dispatch";
+    readonly CANCEL: "cancel";
+    /** Take work: begin or continue the queue. */
+    readonly START: "start";
+    /** Finish the current unit, then take no more; the queue is kept. */
+    readonly STOP: "stop";
+    /** Halt at the next safe point, holding the current unit; nothing new starts. */
+    readonly PAUSE: "pause";
+    /** Continue after a pause. */
+    readonly RESUME: "resume";
+    /** Load a recipe version the machine holds (`args.recipe`); refused when it holds none. */
+    readonly CHANGEOVER: "changeover";
+    readonly ACKNOWLEDGE_ALARM: "ack-alarm";
+    readonly SNAPSHOT: "snapshot";
+};
+export type Op = typeof OP[keyof typeof OP];
+/** Commands a host may ask of a machine through a machine-command row. */
+export declare const CONTROL_OPS: readonly Op[];
+/**
+ * A command's reply. `accepted` means recorded; a machine that prepares the work first (fetch, verify)
+ * may later send `completed` (ready) or `failed` under the same cmdId.
+ */
+export declare const REPLY_STATUS: {
+    readonly ACCEPTED: "accepted";
+    readonly COMPLETED: "completed";
+    readonly REFUSED: "refused";
+    readonly FAILED: "failed";
+};
+export type ReplyStatus = typeof REPLY_STATUS[keyof typeof REPLY_STATUS];

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

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * The line protocol: how a machine on an automated line talks to the line
+ * controller over MQTT. Each machine publishes under its own subtree and
+ * hears only its own commands. Every message is a small JSON envelope.
+ *
+ *   {root}/{site}/{line}/{machine}/presence     retained; birth and will, with the software version
+ *   {root}/{site}/{line}/{machine}/snapshot     retained; full machine state and its boot id
+ *   {root}/{site}/{line}/{machine}/job          job lifecycle and unit handoff
+ *   {root}/{site}/{line}/{machine}/alarm/{id}   retained while active
+ *   {root}/{site}/{line}/{machine}/telemetry    best effort readings
+ *   {root}/{site}/{line}/{machine}/cmd          controller to machine
+ *   {root}/{site}/{line}/{machine}/cmd/reply    machine to controller
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLY_STATUS = exports.CONTROL_OPS = exports.OP = exports.TRANSFER_FAILURE = exports.JOB_RESULT = exports.JOB_EVENT = exports.STOPPING_LEVELS = exports.LEVEL = exports.PRODUCTIVE_MODES = exports.MODE = exports.CHANNEL = exports.SNAPSHOT_HEARTBEAT_SEC = exports.PRESENCE_HEARTBEAT_SEC = exports.MAX_PAYLOAD_BYTES = exports.REPLY_DEADLINE_MS = exports.QOS = exports.PROTOCOL_VERSION = void 0;
+exports.PROTOCOL_VERSION = '1';
+exports.QOS = { BEST_EFFORT: 0, RELIABLE: 1 };
+/** A command with no reply inside this window counts as refused. */
+exports.REPLY_DEADLINE_MS = 5_000;
+exports.MAX_PAYLOAD_BYTES = 256 * 1024;
+exports.PRESENCE_HEARTBEAT_SEC = 30;
+exports.SNAPSHOT_HEARTBEAT_SEC = 60;
+exports.CHANNEL = {
+    PRESENCE: 'presence',
+    SNAPSHOT: 'snapshot',
+    JOB: 'job',
+    ALARM: 'alarm',
+    TELEMETRY: 'telemetry',
+    CMD: 'cmd',
+    REPLY: 'cmd/reply',
+    /** report/<name>: production, availability, inventory and other reporting, kept in the event stream. */
+    REPORT: 'report',
+};
+exports.MODE = {
+    IDLE: 'idle',
+    RUNNING: 'running',
+    CHANGEOVER: 'changeover',
+    FAULTED: 'faulted',
+    EMERGENCY_STOP: 'emergency-stop',
+    MAINTENANCE: 'maintenance',
+};
+exports.PRODUCTIVE_MODES = [exports.MODE.IDLE, exports.MODE.RUNNING];
+exports.LEVEL = { INFO: 'info', WARNING: 'warning', CRITICAL: 'critical', EMERGENCY: 'emergency' };
+/** Levels that stop work and need a person. */
+exports.STOPPING_LEVELS = [exports.LEVEL.CRITICAL, exports.LEVEL.EMERGENCY];
+/**
+ * Job events, one per unit: a job carries one or more units through a
+ * machine together. A unit moves between machines in a handshake: the
+ * receiver says READY, the sender says RELEASED, the receiver confirms
+ * ARRIVED. ARRIVED is the receipt that ends a handoff. WITHDRAWN means the
+ * job left the queue, by a cancel or by the machine giving it up.
+ */
+exports.JOB_EVENT = {
+    QUEUED: 'queued',
+    READY: 'ready',
+    ARRIVED: 'arrived',
+    /** The receiver put the unit on its carrier; some machines report this instead of an arrival. */
+    BOUND: 'bound',
+    STARTED: 'started',
+    PROGRESS: 'progress',
+    FINISHED: 'finished',
+    RELEASED: 'released',
+    TRANSFER_FAILED: 'transfer-failed',
+    WITHDRAWN: 'withdrawn',
+};
+exports.JOB_RESULT = { OK: 'ok', REJECT: 'reject', HOLD: 'hold', SCRAP: 'scrap', REWORK: 'rework' };
+exports.TRANSFER_FAILURE = {
+    JAM: 'jam',
+    INCOMPLETE_HANDSHAKE: 'incomplete-handshake',
+    CARRIER_MISMATCH: 'carrier-mismatch',
+    UNREADABLE_ID: 'unreadable-id',
+};
+/** Commands. Every command carries a cmdId; a repeated cmdId is answered, never run twice. */
+exports.OP = {
+    DISPATCH: 'dispatch',
+    CANCEL: 'cancel',
+    /** Take work: begin or continue the queue. */
+    START: 'start',
+    /** Finish the current unit, then take no more; the queue is kept. */
+    STOP: 'stop',
+    /** Halt at the next safe point, holding the current unit; nothing new starts. */
+    PAUSE: 'pause',
+    /** Continue after a pause. */
+    RESUME: 'resume',
+    /** Load a recipe version the machine holds (`args.recipe`); refused when it holds none. */
+    CHANGEOVER: 'changeover',
+    ACKNOWLEDGE_ALARM: 'ack-alarm',
+    SNAPSHOT: 'snapshot',
+};
+/** Commands a host may ask of a machine through a machine-command row. */
+exports.CONTROL_OPS = [exports.OP.START, exports.OP.STOP, exports.OP.PAUSE, exports.OP.RESUME, exports.OP.CHANGEOVER, exports.OP.CANCEL];
+/**
+ * A command's reply. `accepted` means recorded; a machine that prepares the work first (fetch, verify)
+ * may later send `completed` (ready) or `failed` under the same cmdId.
+ */
+exports.REPLY_STATUS = { ACCEPTED: 'accepted', COMPLETED: 'completed', REFUSED: 'refused', FAILED: 'failed' };

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+import { type Envelope } from './envelope';
+import { type ParsedTopic } from './topics';
+export interface Inspection {
+    parsed: ParsedTopic | null;
+    body: Envelope | null;
+    violations: string[];
+    /** Set by a codec whose machines await a receipt: the id to confirm once the gateway is done with the message. */
+    receiptId?: string;
+    /** The station the message says it comes from, when the wire names one apart from the address (a line that learns addresses). */
+    claim?: string;
+}
+/** Validate one message. `retained` is the publisher's flag when the transport reports it. */
+export declare function inspectMessage(root: string, topic: string, raw: string | Buffer, retained?: boolean): Inspection;

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

@@ -0,0 +1,141 @@
+"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),
+        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,
+        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 };
+}
+/** 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 ?? {};
+    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) {
+        // 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))
+                    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/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/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;