@hotmeshio/long-tail 0.25.4 → 0.27.0

package/README.md

@@ -246,6 +246,7 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](https
 | [Schema Enforcement](https://github.com/hotmeshio/long-tail/blob/main/docs/schema-enforcement.md) | form_schema as an enforced API contract on every resolve surface |
 | [Code-Owned Configuration](https://github.com/hotmeshio/long-tail/blob/main/docs/code-owned-configuration.md) | `configSource` — declared config compared and applied at every boot |
 | [Faceted Routing](https://github.com/hotmeshio/long-tail/blob/main/docs/faceted-routing.md) | Query and atomically claim the queue by facets; dispatcher pattern |
+| [Machines](https://github.com/hotmeshio/long-tail/blob/main/docs/machines.md) | `start({ machines })`: machines resolve escalation rows over MQTT, as people do with forms |
 | [SDK](https://github.com/hotmeshio/long-tail/blob/main/docs/sdk.md) | Embedded usage, `createClient`, event subscriptions |
 | [Architecture](https://github.com/hotmeshio/long-tail/blob/main/docs/architecture.md) | Project structure, conventions, discovery |
 | [Cloud](https://github.com/hotmeshio/long-tail/blob/main/docs/cloud.md) | AWS ECS, GCP Cloud Run, Docker |

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';
@@ -50,4 +54,5 @@ export { resolveCredential } from './services/iam/credentials';
 export * as KnowledgeApi from './api/knowledge';
 export type { LTClient, LTClientOptions } from './sdk';
 export * as api from './api';
+export * as Machines from './services/machines';
 export { LTExpressAdapter } from './adapters/express';

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,13 +32,18 @@ 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.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 ─────────────────────────────────────────────────────────
 var start_2 = require("./start");
 Object.defineProperty(exports, "start", { enumerable: true, get: function () { return start_2.start; } });
@@ -99,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");
@@ -151,6 +163,7 @@ var credentials_1 = require("./services/iam/credentials");
 Object.defineProperty(exports, "resolveCredential", { enumerable: true, get: function () { return credentials_1.resolveCredential; } });
 exports.KnowledgeApi = __importStar(require("./api/knowledge"));
 exports.api = __importStar(require("./api"));
+exports.Machines = __importStar(require("./services/machines"));
 var express_1 = require("./adapters/express");
 Object.defineProperty(exports, "LTExpressAdapter", { enumerable: true, get: function () { return express_1.LTExpressAdapter; } });
 // ─── Server ──────────────────────────────────────────────────────────────────
@@ -252,6 +265,11 @@ async function main() {
         escalation: {
             strategy: 'mcp',
         },
+        // 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
+            ? machinesFromEnv(process.env.MACHINE_LINE_CONFIG, process.env.MACHINE_CODEC_MODULE)
+            : undefined,
         branding: {
             ...(process.env.WHITE_LABEL ? { appName: process.env.WHITE_LABEL } : {}),
             // Midnight ships as a registered theme — the working proof that a
@@ -259,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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,22 @@
+"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("./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/line.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The line: site, line and the machines on it, in route order, read from a
+ * JSON file (MACHINE_LINE_CONFIG) or passed in by the host.
+ */
+import type { LineDef, MachineDef, MachineIdent, MaterialDef, MeasurementDef } from '../../types/machines';
+export type { LineDef, MachineDef, MaterialDef, MeasurementDef };
+/** How a line knows its machines' addresses (`LineDef.addressing`). */
+export declare const ADDRESSING: {
+    readonly DECLARED: "declared";
+    readonly LEARNED: "learned";
+};
+/** Whether the line learns this station's address from the machine that claims it. */
+export declare function learnsAddress(line: LineDef, machineId: string): boolean;
+/** Which machine puts a unit on its carrier plate and which takes it off. */
+export declare const CARRIER_ROLE: {
+    readonly BIND: "bind";
+    readonly RELEASE: "release";
+    readonly NONE: "none";
+};
+export type CarrierRole = typeof CARRIER_ROLE[keyof typeof CARRIER_ROLE];
+/** Reject a line whose identifiers would not survive the topic mapping. */
+export declare function validateLine(line: LineDef): LineDef;
+/** The line at `path` (JSON), or `fallback` when no path is given. */
+export declare function loadLine(path: string | undefined, fallback?: LineDef): LineDef;
+export declare function identOf(line: LineDef, machineId: string): MachineIdent;
+export declare function machineById(line: LineDef, machineId: string): MachineDef;
+/** The broker identity of each machine whose address the line declares, {site}-{line}-{address}. */
+export declare function clientIds(line: LineDef): string[];
+/** The broker and Long Tail identity of the line's gateway. */
+export declare function controllerId(line: LineDef): string;
+/** The default role name for a process. */
+export declare function stationRole(process: string): string;
+export declare const DEFAULT_EXIT_ROLE = "line-exit";
+export declare const DEFAULT_OPERATOR_ROLE = "line-operator";
+/** The Long Tail role a machine resolves handoffs under. */
+export declare function machineRole(def: Pick<MachineDef, 'role' | 'process'>): string;
+/** Every station role on the line, once each, in route order. */
+export declare function stationRoles(line: LineDef): string[];
+/** The role of the person who receives units at line exit. */
+export declare function exitRole(line: LineDef): string;
+/** Roles of people who take units straight from a machine: the exit role and any receivers. */
+export declare function receiverRoles(line: LineDef): string[];
+/** The role of the person who decides failed handoffs and closes alarm and machine rows. */
+export declare function operatorRole(line: LineDef): string;

package/build/lib/machines/line.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * The line: site, line and the machines on it, in route order, read from a
+ * JSON file (MACHINE_LINE_CONFIG) or passed in by the host.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPERATOR_ROLE = exports.DEFAULT_EXIT_ROLE = exports.CARRIER_ROLE = exports.ADDRESSING = void 0;
+exports.learnsAddress = learnsAddress;
+exports.validateLine = validateLine;
+exports.loadLine = loadLine;
+exports.identOf = identOf;
+exports.machineById = machineById;
+exports.clientIds = clientIds;
+exports.controllerId = controllerId;
+exports.stationRole = stationRole;
+exports.machineRole = machineRole;
+exports.stationRoles = stationRoles;
+exports.exitRole = exitRole;
+exports.receiverRoles = receiverRoles;
+exports.operatorRole = operatorRole;
+const fs_1 = require("fs");
+const protocol_1 = require("./protocol");
+/** How a line knows its machines' addresses (`LineDef.addressing`). */
+exports.ADDRESSING = { DECLARED: 'declared', LEARNED: 'learned' };
+/** Whether the line learns this station's address from the machine that claims it. */
+function learnsAddress(line, machineId) {
+    return line.addressing === exports.ADDRESSING.LEARNED && !line.machines.find((m) => m.machineId === machineId)?.address;
+}
+/** Which machine puts a unit on its carrier plate and which takes it off. */
+exports.CARRIER_ROLE = { BIND: 'bind', RELEASE: 'release', NONE: 'none' };
+/** Reject a line whose identifiers would not survive the topic mapping. */
+function validateLine(line) {
+    (0, protocol_1.assertTopicLevel)('siteId', line.siteId);
+    (0, protocol_1.assertTopicLevel)('lineId', line.lineId);
+    if (!line.machines?.length)
+        throw new Error('line has no machines');
+    if (line.addressing && !Object.values(exports.ADDRESSING).includes(line.addressing)) {
+        throw new Error(`addressing must be one of ${Object.values(exports.ADDRESSING).join(', ')}`);
+    }
+    const seen = new Set();
+    const addresses = new Set();
+    for (const m of line.machines) {
+        (0, protocol_1.assertTopicLevel)('machineId', m.machineId);
+        if (seen.has(m.machineId))
+            throw new Error(`duplicate machineId "${m.machineId}"`);
+        seen.add(m.machineId);
+        if (!learnsAddress(line, m.machineId)) {
+            const address = m.address ?? m.machineId;
+            (0, protocol_1.assertTopicLevel)('address', address);
+            if (addresses.has(address))
+                throw new Error(`duplicate address "${address}"`);
+            addresses.add(address);
+        }
+        if (!(m.cycleSec > 0))
+            throw new Error(`${m.machineId}: cycleSec must be positive`);
+        if (m.queueDepth !== undefined && !(Number.isInteger(m.queueDepth) && m.queueDepth >= 1)) {
+            throw new Error(`${m.machineId}: queueDepth must be a whole number of at least 1`);
+        }
+    }
+    return line;
+}
+/** The line at `path` (JSON), or `fallback` when no path is given. */
+function loadLine(path, fallback) {
+    if (!path) {
+        if (!fallback)
+            throw new Error('no line definition: set MACHINE_LINE_CONFIG or pass one');
+        return validateLine(fallback);
+    }
+    return validateLine(JSON.parse((0, fs_1.readFileSync)(path, 'utf8')));
+}
+function identOf(line, machineId) {
+    const address = line.machines.find((m) => m.machineId === machineId)?.address;
+    return { siteId: line.siteId, lineId: line.lineId, machineId, ...(address ? { address } : {}) };
+}
+function machineById(line, machineId) {
+    const def = line.machines.find((m) => m.machineId === machineId);
+    if (!def)
+        throw new Error(`machine "${machineId}" is not on ${line.siteId}/${line.lineId}`);
+    return def;
+}
+/** The broker identity of each machine whose address the line declares, {site}-{line}-{address}. */
+function clientIds(line) {
+    return line.machines.filter((m) => !learnsAddress(line, m.machineId)).map((m) => (0, protocol_1.clientIdOf)(identOf(line, m.machineId)));
+}
+/** The broker and Long Tail identity of the line's gateway. */
+function controllerId(line) {
+    return `line-controller-${line.siteId}-${line.lineId}`;
+}
+/** The default role name for a process. */
+function stationRole(process) {
+    return `line-${process.replace(/_/g, '-')}`;
+}
+exports.DEFAULT_EXIT_ROLE = 'line-exit';
+exports.DEFAULT_OPERATOR_ROLE = 'line-operator';
+/** The Long Tail role a machine resolves handoffs under. */
+function machineRole(def) {
+    return def.role ?? stationRole(def.process);
+}
+/** Every station role on the line, once each, in route order. */
+function stationRoles(line) {
+    return [...new Set(line.machines.map(machineRole))];
+}
+/** The role of the person who receives units at line exit. */
+function exitRole(line) {
+    return line.roles?.exit ?? exports.DEFAULT_EXIT_ROLE;
+}
+/** Roles of people who take units straight from a machine: the exit role and any receivers. */
+function receiverRoles(line) {
+    return [...new Set([exitRole(line), ...(line.roles?.receivers ?? [])])];
+}
+/** The role of the person who decides failed handoffs and closes alarm and machine rows. */
+function operatorRole(line) {
+    return line.roles?.operator ?? exports.DEFAULT_OPERATOR_ROLE;
+}

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

@@ -0,0 +1,108 @@
+/**
+ * The wire, behind one seam. A codec turns a machine's MQTT messages into
+ * the line protocol's events (topics.ts, contract.ts) and the gateway's
+ * commands back into MQTT messages. The gateway, the rows and the workflow
+ * only ever see the line protocol. The generic codec speaks it natively; a
+ * host whose machines speak another protocol supplies a codec for it.
+ */
+import type { LineDef } from '../../../types/machines';
+import { type Inspection } from './contract';
+import { type MachineIdent } from './envelope';
+export interface WireMessage {
+    topic: string;
+    payload: string;
+}
+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 {
+    /** Messages the gateway acts on; kept in the durable event stream. */
+    events: string[];
+    /** Readings that only prove a machine is alive; read live. */
+    telemetry: string[];
+    /** Where a machine reads its commands; only the line controller writes them. */
+    commands: string[];
+}
+/** Which topics a filter covers: a level left out matches any (`+`). */
+export interface TopicScope {
+    siteId?: string;
+    lineId?: string;
+    /** The machine's wire address (`MachineDef.address`, else its id). */
+    address?: string;
+}
+export interface LineCodec {
+    readonly root: string;
+    readonly channels: CodecChannels;
+    /**
+     * The topic of one machine channel. Defaults to `{root}/{site}/{line}/{address}/{channel}`.
+     * A layout must begin with `{root}/{site}/{line}/`, the prefix the line's subscription and
+     * retained reads use; the ACL and stream subjects are built from this.
+     */
+    topicFor?(scope: TopicScope, channel: string): string;
+    /** Most units one dispatch may carry; the gateway sends one dispatch per unit when 1. Null: any. */
+    readonly unitsPerDispatch: number | null;
+    /**
+     * When a handoff's job goes to its receiver: as soon as the row exists (the default), or once every
+     * unit has arrived there, for machines that take work only for units they have scanned in. Each
+     * dispatched unit then carries the arrival event its receiver reported.
+     */
+    readonly dispatchOn?: DispatchOn;
+    /**
+     * Strict: a message with contract violations is confirmed but never acted on, and a row shows it
+     * 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. */
+    encode(ident: MachineIdent, command: MachineCommand): WireMessage[];
+    /**
+     * The receipt confirming messages the gateway is done with (each decoded with a `receiptId`), for
+     * machines that keep an outbox until confirmed. Absent: no receipts are sent.
+     */
+    receipt?(ident: MachineIdent, messageIds: string[]): WireMessage[];
+}
+export declare const DISPATCH_ON: {
+    readonly CREATED: "created";
+    readonly ARRIVAL: "arrival";
+};
+export type DispatchOn = typeof DISPATCH_ON[keyof typeof DISPATCH_ON];
+/** Which job event counts as the receiver's receipt. */
+export declare const RECEIPT_FROM: {
+    readonly ARRIVED: "arrived";
+    readonly BOUND: "bound";
+    readonly STARTED: "started";
+};
+export type ReceiptFrom = typeof RECEIPT_FROM[keyof typeof RECEIPT_FROM];
+export interface GenericCodecOptions {
+    root: string;
+    /** Maps topic levels back to machine ids for machines whose `address` differs from their id. */
+    line?: Pick<LineDef, 'machines'>;
+    /** For machines that report no arrival: treat the receiver's carrier bind or job start as the receipt. */
+    receiptFrom?: ReceiptFrom;
+    unitsPerDispatch?: number | null;
+    dispatchOn?: DispatchOn;
+}
+export declare const GENERIC_CHANNELS: CodecChannels;
+/** The topic of one machine channel under the codec's layout. */
+export declare function topicOf(codec: Pick<LineCodec, 'root' | 'topicFor'>, scope: TopicScope, channel: string): string;
+export declare function genericCodec(opts: GenericCodecOptions): LineCodec;

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

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * The wire, behind one seam. A codec turns a machine's MQTT messages into
+ * the line protocol's events (topics.ts, contract.ts) and the gateway's
+ * commands back into MQTT messages. The gateway, the rows and the workflow
+ * only ever see the line protocol. The generic codec speaks it natively; a
+ * host whose machines speak another protocol supplies a codec for it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GENERIC_CHANNELS = exports.RECEIPT_FROM = exports.DISPATCH_ON = void 0;
+exports.topicOf = topicOf;
+exports.genericCodec = genericCodec;
+const constants_1 = require("./constants");
+const contract_1 = require("./contract");
+const envelope_1 = require("./envelope");
+const topics_1 = require("./topics");
+exports.DISPATCH_ON = { CREATED: 'created', ARRIVAL: 'arrival' };
+/** Which job event counts as the receiver's receipt. */
+exports.RECEIPT_FROM = { ARRIVED: 'arrived', BOUND: 'bound', STARTED: 'started' };
+exports.GENERIC_CHANNELS = {
+    events: [constants_1.CHANNEL.PRESENCE, constants_1.CHANNEL.SNAPSHOT, constants_1.CHANNEL.JOB, `${constants_1.CHANNEL.ALARM}/+`, constants_1.CHANNEL.REPLY, `${constants_1.CHANNEL.REPORT}/#`],
+    telemetry: [constants_1.CHANNEL.TELEMETRY],
+    commands: [constants_1.CHANNEL.CMD],
+};
+/** The topic of one machine channel under the codec's layout. */
+function topicOf(codec, scope, channel) {
+    if (codec.topicFor)
+        return codec.topicFor(scope, channel);
+    const level = (v) => v ?? '+';
+    return `${codec.root}/${level(scope.siteId)}/${level(scope.lineId)}/${level(scope.address)}/${channel}`;
+}
+/** Topic level to machine id, for the machines whose address is not their id. */
+function addressMap(line) {
+    return new Map((line?.machines ?? []).filter((m) => m.address && m.address !== m.machineId).map((m) => [m.address, m.machineId]));
+}
+/** The inspection with the topic's address read back as the machine id; an unknown address keeps the station its message claims. */
+function atMachine(seen, ids) {
+    const machineId = seen.parsed && ids.get(seen.parsed.ident.machineId);
+    if (!machineId) {
+        const station = seen.body?.source?.station;
+        return typeof station === 'string' && station ? { ...seen, claim: station } : seen;
+    }
+    const ident = { ...seen.parsed.ident, machineId, address: seen.parsed.ident.machineId };
+    return { ...seen, parsed: { ...seen.parsed, ident } };
+}
+function withEvent(seen, event) {
+    const body = seen.body;
+    return { ...seen, body: { ...body, body: { ...body.body, event } } };
+}
+/** Another event as the receipt: the arrival first, then that event; reported arrivals are dropped. */
+function inferReceipt(seen, from) {
+    if (seen.parsed?.kind !== topics_1.MESSAGE_KIND.JOB || !seen.body)
+        return [seen];
+    const event = seen.body.body?.event;
+    if (event === constants_1.JOB_EVENT.ARRIVED)
+        return [];
+    if (event === from)
+        return [withEvent(seen, constants_1.JOB_EVENT.ARRIVED), seen];
+    return [seen];
+}
+function genericCodec(opts) {
+    const receiptFrom = opts.receiptFrom ?? exports.RECEIPT_FROM.ARRIVED;
+    const ids = addressMap(opts.line);
+    return {
+        root: opts.root,
+        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)
+                return [];
+            return receiptFrom === exports.RECEIPT_FROM.ARRIVED ? [seen] : inferReceipt(seen, receiptFrom);
+        },
+        encode(ident, command) {
+            return [{ topic: (0, topics_1.machineTopic)(opts.root, ident, constants_1.CHANNEL.CMD), payload: JSON.stringify((0, envelope_1.buildEnvelope)(ident, command)) }];
+        },
+    };
+}