@hotmeshio/long-tail 0.26.0 → 0.28.0

package/README.md

@@ -63,6 +63,12 @@ The `reviewer` role owns a versioned form schema. The platform renders it as the
 
 Two surfaces, one model. A `proxyActivity` targets a machine: call it, get a result. `conditional` targets the external world — a reviewer, an operator, a factory cell. It suspends the workflow and writes a single escalation row carrying everything needed to route the work: the `role` that should act, its `type` and `priority`, and any `metadata` to display or filter on. People work that row through an RBAC-scoped surface — find it, claim it, resolve it — from the dashboard, the API, or MCP, and resolving it resumes the workflow exactly where it paused.
 
+Three kinds of resolver answer the same row:
+
+- **People**, on the [dashboard](https://github.com/hotmeshio/long-tail/blob/main/docs/dashboard.md): the role's versioned form is their UI.
+- **Systems and agents**, over the [API](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/escalations.md) and MCP: the same find, claim and resolve verbs, as a service account.
+- **Machines**, over [MQTT](https://github.com/hotmeshio/long-tail/blob/main/docs/machines.md): a line's gateway claims and resolves as each machine, and the protocol lands on the row as data; the dashboard's Lines view watches the wire, and lines are declared in code or through the API.
+
 Activities are plain functions:
 
 ```typescript
@@ -76,7 +82,7 @@ export async function analyzeContent(content: string) {
 
 The non-deterministic queue has qualities the deterministic one never needed:
 
-- **RBAC is intrinsic.** The queue is a role; permission lives in the queue itself. Any member answers — a person in the dashboard, a service account through the API — and the workflow is indifferent to which.
+- **RBAC is intrinsic.** The queue is a role; permission lives in the queue itself. Any member answers — a person in the dashboard, a service account through the API, a machine over MQTT — and the workflow is indifferent to which.
 - **The form is data.** A versioned JSON Schema on the role renders the resolver's UI — fields, validation, conditionals, layout — with zero frontend code. Assign an escalation to one named user with self scope and you have a just-in-time form: one person, one item, one auditable edition.
 - **Claims are locks.** A claim is a TTL window with an extend prompt before it lapses and a resolve guard behind it — the platform rejects a submission against an expired claim atomically, in the same statement that settles the row. Stale work cannot land.
 - **Cancel is home.** Cancellation is a first-class settlement, not an exception. When the pressure no longer applies, the waiting flow sees `null` and reconciles to a modeled resting state. Handled is broader than resolved — timeout, cancel, and hop-onward are all endings the loop was built to reach.
@@ -170,6 +176,7 @@ const lt = await start({
   telemetry: { honeycomb: { apiKey: process.env.HNY } },
   logging: { pino: { level: 'info' } },
   maintenance: true,
+  machines: { lines: [Machines.loadLine('/etc/line.json')] },  // rows resolved over MQTT; the dashboard gains a Lines view
 });
 ```
 
@@ -246,7 +253,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 |
+| [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; the Lines view, the line registry API and the machines MCP server |
 | [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/api/settings.d.ts

@@ -8,6 +8,9 @@ import type { LTApiResult } from '../types/sdk';
  * environment block (long-tail + HotMesh versions, Node env/version).
  *
  * @param req — the incoming HTTP request, used to derive NATS WS URL from headers when proxying
- * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, search, branding, display, environment } }`
+ * `machines` is present only when `start({ machines })` runs a surface; it carries the
+ * number of lines this replica runs and nothing else, since the settings are public.
+ *
+ * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, search, branding, display, environment, machines? } }`
  */
 export declare function getSettings(req?: IncomingMessage): Promise<LTApiResult>;

package/build/api/settings.js

@@ -12,6 +12,7 @@ const search_1 = require("../modules/search");
 const branding_1 = require("../modules/branding");
 const oauth_server_1 = require("../modules/oauth-server");
 const display_1 = require("../modules/display");
+const machines_1 = require("../modules/machines");
 const version_1 = require("../modules/version");
 const sso_1 = require("../modules/sso");
 const defaults_1 = require("../modules/defaults");
@@ -43,7 +44,10 @@ function resolveNatsWsUrl(adapter, req) {
  * environment block (long-tail + HotMesh versions, Node env/version).
  *
  * @param req — the incoming HTTP request, used to derive NATS WS URL from headers when proxying
- * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, search, branding, display, environment } }`
+ * `machines` is present only when `start({ machines })` runs a surface; it carries the
+ * number of lines this replica runs and nothing else, since the settings are public.
+ *
+ * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, search, branding, display, environment, machines? } }`
  */
 async function getSettings(req) {
     try {
@@ -55,6 +59,7 @@ async function getSettings(req) {
         // connect via NATS instead of Socket.IO.
         const forceNats = config_1.config.EVENT_TRANSPORT === 'nats';
         const transport = forceNats && natsAdapter ? 'nats' : hasSocketIO ? 'socketio' : natsAdapter ? 'nats' : 'none';
+        const machines = (0, machines_1.getMachineSurface)();
         return {
             status: 200,
             data: {
@@ -97,6 +102,7 @@ async function getSettings(req) {
                     nodeVersion: process.version,
                     eventTransport: transport,
                 },
+                ...(machines ? { machines: { declared: machines.describeLines().length } } : {}),
             },
         };
     }

package/build/index.d.ts

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

package/build/index.js

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

package/build/lib/db/config-lock.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Serializes multi-statement config writes (role-list replaces, escalation
+ * target replaces, line declarations) across concurrently booting containers
+ * and live API writes. Single-statement upserts are individually race-safe;
+ * the lock exists for the replace transactions and keeps boot reports
+ * coherent. Distinct from the migration lock so a slow migration on one
+ * container never blocks another's config pass behind two locks at once.
+ */
+export declare const CONFIG_APPLY_LOCK_ID = 8675310;
+export declare function withConfigLock<T>(fn: () => Promise<T>): Promise<T>;

package/build/lib/db/config-lock.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_APPLY_LOCK_ID = void 0;
+exports.withConfigLock = withConfigLock;
+const index_1 = require("./index");
+/**
+ * Serializes multi-statement config writes (role-list replaces, escalation
+ * target replaces, line declarations) across concurrently booting containers
+ * and live API writes. Single-statement upserts are individually race-safe;
+ * the lock exists for the replace transactions and keeps boot reports
+ * coherent. Distinct from the migration lock so a slow migration on one
+ * container never blocks another's config pass behind two locks at once.
+ */
+exports.CONFIG_APPLY_LOCK_ID = 8675310;
+async function withConfigLock(fn) {
+    const pool = (0, index_1.getPool)();
+    const client = await pool.connect();
+    try {
+        await client.query(`SELECT pg_advisory_lock(${exports.CONFIG_APPLY_LOCK_ID})`);
+        return await fn();
+    }
+    finally {
+        await client
+            .query(`SELECT pg_advisory_unlock(${exports.CONFIG_APPLY_LOCK_ID})`)
+            .catch(() => { });
+        client.release();
+    }
+}

package/build/lib/db/schemas/041_machine_lines.sql

@@ -0,0 +1,26 @@
+-- Migration 041: The machine line registry
+--
+-- One row per line a deployment controls: the line definition as the
+-- gateway reads it (site, line, machines in route order), who declared it,
+-- and a version that advances on every change. Lines declared in code
+-- (start({ machines })) are applied here at boot under the configSource
+-- rules; lines declared through PUT /api/machines/lines live here alone.
+-- Every replica reads the registry to know which lines to contend for, and
+-- the Lines index reads it with the pending rows that say how each line is.
+-- search_text is the service's lowercase projection of site, line, machine
+-- ids, processes, roles and addresses, for the index's search.
+
+CREATE TABLE IF NOT EXISTS lt_machine_lines (
+  site_id     TEXT NOT NULL,
+  line_id     TEXT NOT NULL,
+  definition  JSONB NOT NULL,
+  source      TEXT NOT NULL CHECK (source IN ('code', 'api')),
+  version     INT NOT NULL DEFAULT 1,
+  enabled     BOOLEAN NOT NULL DEFAULT true,
+  search_text TEXT NOT NULL,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (site_id, line_id)
+);
+
+CREATE INDEX IF NOT EXISTS lt_machine_lines_site_idx ON lt_machine_lines (site_id, line_id);

package/build/lib/events/browser-view.js

@@ -41,13 +41,15 @@ exports.holderView = holderView;
 /**
  * What a browser receives of an event. Builders receive events whole. Anyone
  * else receives enough to route and refresh: escalation events keep their
- * routing fields, and every other event arrives without `data` and
- * `milestones`. Full records are read through the scoped API, by id.
+ * routing fields, machine wire events keep everything but the raw payload,
+ * and every other event arrives without `data` and `milestones`. Full
+ * records are read through the scoped API, by id.
  *
  * Server-side consumers (agent triggers, callbacks) are unaffected: this view
  * applies only where events leave for a browser.
  */
 const ESCALATION_SUBJECT = 'system.escalation.';
+const MACHINE_WIRE_SUBJECT = 'machine.wire.';
 const ACTIVE_ACCOUNT = 'active';
 /** Escalation event fields a browser needs to route a refresh and follow a claim. */
 exports.BROWSER_ESCALATION_FIELDS = [
@@ -69,6 +71,10 @@ function eventForViewer(event, viewer) {
         }
         return { ...rest, data: kept };
     }
+    if (typeof event.type === 'string' && event.type.startsWith(MACHINE_WIRE_SUBJECT) && data) {
+        const { payload: _payload, ...wire } = data;
+        return { ...rest, data: wire };
+    }
     return rest;
 }
 /**

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/events/publish.d.ts

@@ -1,4 +1,5 @@
 import type { LTMilestone } from '../../types';
+import type { WireEvent } from '../../types/machines-view';
 /**
  * Publish a milestone event. Called from handleCompletion (workflow
  * interceptor), ltCompleteTask (orchestrator activity), and the
@@ -124,3 +125,35 @@ export declare function publishWorkflowEvent(params: {
     status: string;
     data?: Record<string, any>;
 }): Promise<void>;
+/** The subject family of every message a line's gateway reads or sends. */
+export declare const MACHINE_WIRE_TYPE = "machine.wire";
+/** The subject family of the gateway log. */
+export declare const MACHINE_LOG_TYPE = "machine.log";
+/** The machine token of a wire event from an address no station claims. */
+export declare const MACHINE_UNKNOWN_TOKEN = "unknown";
+/**
+ * Publish one wire record from a line's gateway.
+ * Subject: machine.wire.{site}.{line}.{machineId|unknown}.{in|out}
+ */
+export declare function publishMachineWireEvent(event: WireEvent): Promise<void>;
+/** The log event as one subject token: `machine_gateway.dispatch.accepted` becomes `dispatch-accepted`. */
+export declare function machineLogToken(event: string): string;
+/**
+ * Publish one gateway log entry.
+ * Subject: machine.log.{site}.{line}.{event}
+ */
+export declare function publishMachineLogEvent(params: {
+    siteId: string;
+    lineId: string;
+    level: 'info' | 'warn' | 'error';
+    event: string;
+    context?: Record<string, unknown>;
+}): Promise<void>;
+/** A line declared or retired in the registry; every replica reads the row again and follows. */
+export declare function publishMachineLineEvent(params: {
+    siteId: string;
+    lineId: string;
+    source: 'code' | 'api';
+    version: number;
+    action: 'declared' | 'retired';
+}): Promise<void>;

package/build/lib/events/publish.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ANNOUNCEMENT_TOPIC = void 0;
+exports.MACHINE_UNKNOWN_TOKEN = exports.MACHINE_LOG_TYPE = exports.MACHINE_WIRE_TYPE = exports.ANNOUNCEMENT_TOPIC = void 0;
 exports.publishMilestoneEvent = publishMilestoneEvent;
 exports.publishTaskEvent = publishTaskEvent;
 exports.publishEscalationEvent = publishEscalationEvent;
@@ -10,6 +10,10 @@ exports.publishKnowledgeEvent = publishKnowledgeEvent;
 exports.publishFileEvent = publishFileEvent;
 exports.publishAgentEvent = publishAgentEvent;
 exports.publishWorkflowEvent = publishWorkflowEvent;
+exports.publishMachineWireEvent = publishMachineWireEvent;
+exports.machineLogToken = machineLogToken;
+exports.publishMachineLogEvent = publishMachineLogEvent;
+exports.publishMachineLineEvent = publishMachineLineEvent;
 const index_1 = require("./index");
 const matching_1 = require("./matching");
 const logger_1 = require("../logger");
@@ -202,3 +206,50 @@ function publishWorkflowEvent(params) {
         timestamp: new Date().toISOString(),
     });
 }
+/** The subject family of every message a line's gateway reads or sends. */
+exports.MACHINE_WIRE_TYPE = 'machine.wire';
+/** The subject family of the gateway log. */
+exports.MACHINE_LOG_TYPE = 'machine.log';
+/** The machine token of a wire event from an address no station claims. */
+exports.MACHINE_UNKNOWN_TOKEN = 'unknown';
+const MACHINE_SOURCE = 'machine-gateway';
+/**
+ * Publish one wire record from a line's gateway.
+ * Subject: machine.wire.{site}.{line}.{machineId|unknown}.{in|out}
+ */
+function publishMachineWireEvent(event) {
+    const machine = event.machineId ? (0, matching_1.sanitizeSubjectToken)(event.machineId) : exports.MACHINE_UNKNOWN_TOKEN;
+    return fireAndForget({
+        type: `${exports.MACHINE_WIRE_TYPE}.${(0, matching_1.sanitizeSubjectToken)(event.siteId)}.${(0, matching_1.sanitizeSubjectToken)(event.lineId)}.${machine}.${event.direction}`,
+        source: MACHINE_SOURCE,
+        data: event,
+        timestamp: event.at,
+    });
+}
+const GATEWAY_LOG_PREFIX = 'machine_gateway.';
+/** The log event as one subject token: `machine_gateway.dispatch.accepted` becomes `dispatch-accepted`. */
+function machineLogToken(event) {
+    return (0, matching_1.sanitizeSubjectToken)(event.startsWith(GATEWAY_LOG_PREFIX) ? event.slice(GATEWAY_LOG_PREFIX.length) : event);
+}
+/**
+ * Publish one gateway log entry.
+ * Subject: machine.log.{site}.{line}.{event}
+ */
+function publishMachineLogEvent(params) {
+    return fireAndForget({
+        type: `${exports.MACHINE_LOG_TYPE}.${(0, matching_1.sanitizeSubjectToken)(params.siteId)}.${(0, matching_1.sanitizeSubjectToken)(params.lineId)}.${machineLogToken(params.event)}`,
+        source: MACHINE_SOURCE,
+        data: { level: params.level, event: params.event, siteId: params.siteId, lineId: params.lineId, ...(params.context ?? {}) },
+        timestamp: new Date().toISOString(),
+    });
+}
+const MACHINE_LINE_TYPE = 'machine.line';
+/** A line declared or retired in the registry; every replica reads the row again and follows. */
+function publishMachineLineEvent(params) {
+    return fireAndForget({
+        type: `${MACHINE_LINE_TYPE}.${(0, matching_1.sanitizeSubjectToken)(params.siteId)}.${(0, matching_1.sanitizeSubjectToken)(params.lineId)}.${params.action}`,
+        source: MACHINE_SOURCE,
+        data: { ...params },
+        timestamp: new Date().toISOString(),
+    });
+}

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

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

package/build/lib/machines/index.js

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

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

@@ -1,6 +1,7 @@
 /**
  * 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.
+ * JSON file or passed in by the host. MACHINE_LINE_CONFIG names one file, or
+ * several separated by commas.
  */
 import type { LineDef, MachineDef, MachineIdent, MaterialDef, MeasurementDef } from '../../types/machines';
 export type { LineDef, MachineDef, MaterialDef, MeasurementDef };
@@ -22,6 +23,8 @@ export type CarrierRole = typeof CARRIER_ROLE[keyof typeof CARRIER_ROLE];
 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;
+/** Every line in `paths`, a comma-separated list of JSON files (MACHINE_LINE_CONFIG); each site and line once. */
+export declare function loadLines(paths: 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}. */

package/build/lib/machines/line.js

@@ -1,13 +1,15 @@
 "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.
+ * JSON file or passed in by the host. MACHINE_LINE_CONFIG names one file, or
+ * several separated by commas.
  */
 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.loadLines = loadLines;
 exports.identOf = identOf;
 exports.machineById = machineById;
 exports.clientIds = clientIds;
@@ -68,6 +70,21 @@ function loadLine(path, fallback) {
     }
     return validateLine(JSON.parse((0, fs_1.readFileSync)(path, 'utf8')));
 }
+/** Every line in `paths`, a comma-separated list of JSON files (MACHINE_LINE_CONFIG); each site and line once. */
+function loadLines(paths, fallback) {
+    const list = (paths ?? '').split(',').map((p) => p.trim()).filter(Boolean);
+    if (!list.length)
+        return [loadLine(undefined, fallback)];
+    const lines = list.map((p) => loadLine(p));
+    const seen = new Set();
+    for (const line of lines) {
+        const key = `${line.siteId}/${line.lineId}`;
+        if (seen.has(key))
+            throw new Error(`line ${key} is declared twice in MACHINE_LINE_CONFIG`);
+        seen.add(key);
+    }
+    return lines;
+}
 function identOf(line, machineId) {
     const address = line.machines.find((m) => m.machineId === machineId)?.address;
     return { siteId: line.siteId, lineId: line.lineId, machineId, ...(address ? { address } : {}) };

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

@@ -16,6 +16,10 @@ export interface MachineCommand {
     cmdId: string;
     op: string;
     args: Record<string, unknown>;
+    /** How many times this gateway has sent this cmdId, this time included. */
+    attempt?: number;
+    /** The command may have reached the machine before: sent earlier, or its row predates this gateway's takeover. */
+    retry?: boolean;
 }
 /** MQTT filters under each machine's topic, e.g. `job` or `alarm/+`. */
 export interface CodecChannels {
@@ -55,6 +59,24 @@ export interface LineCodec {
      * to a person. Otherwise (the default) known fields are acted on and the violations are logged.
      */
     readonly strict?: boolean;
+    /**
+     * The machines keep no retained state and report only what changes: the gateway asks each one for
+     * a snapshot when it takes the line, so it knows every machine's job before acting on a change.
+     */
+    readonly snapshotOnStart?: boolean;
+    /**
+     * Active alarms stay retained on the broker until they clear, as in the line protocol. A takeover's
+     * retained read is then every active alarm, and an alarm row whose alarm is missing from it cleared
+     * while no gateway listened. Otherwise a machine's snapshot lists its active alarms, and an alarm it
+     * no longer lists has cleared.
+     */
+    readonly retainedAlarms?: boolean;
+    /**
+     * Commands of the machines' own, beyond the line protocol's control ops, that a machine-command row
+     * may ask for. Each is sent through `encode` and the row resolves with the reply. Every entry is a
+     * non-empty string; the gateway refuses a codec whose entries are not.
+     */
+    readonly rowOps?: readonly string[];
     /** 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. */
@@ -65,6 +87,8 @@ export interface LineCodec {
      */
     receipt?(ident: MachineIdent, messageIds: string[]): WireMessage[];
 }
+/** The codec's own row ops, each a non-empty string; anything else is a misconfigured codec and throws. */
+export declare function declaredRowOps(codec: Pick<LineCodec, 'rowOps'>): readonly string[];
 export declare const DISPATCH_ON: {
     readonly CREATED: "created";
     readonly ARRIVAL: "arrival";