@hotmeshio/long-tail 0.27.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.js

@@ -283,15 +283,20 @@ async function main() {
             : undefined,
     });
 }
-/** The configured line, spoken to by the codec MACHINE_CODEC_MODULE names (its `createCodec(line)`), or the generic one. */
+/**
+ * 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 line = (0, line_1.loadLine)(lineConfig);
+    const lines = (0, line_1.loadLines)(lineConfig);
     if (!codecModule)
-        return { lines: [line] };
+        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: [line], codec: createCodec(line) };
+    return { lines, codec: createCodec(lines[0]) };
 }
 // Run server when executed directly
 if (require.main === module) {

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/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/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

@@ -71,6 +71,12 @@ export interface LineCodec {
      * 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. */
@@ -81,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";

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

@@ -8,12 +8,21 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GENERIC_CHANNELS = exports.RECEIPT_FROM = exports.DISPATCH_ON = void 0;
+exports.declaredRowOps = declaredRowOps;
 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");
+/** The codec's own row ops, each a non-empty string; anything else is a misconfigured codec and throws. */
+function declaredRowOps(codec) {
+    const ops = codec.rowOps ?? [];
+    if (!Array.isArray(ops) || ops.some((op) => typeof op !== 'string' || !op)) {
+        throw new Error('codec.rowOps must be a list of non-empty strings');
+    }
+    return ops;
+}
 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' };

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

@@ -93,7 +93,7 @@ export declare const OP: {
     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. */
+    /** Finish the current unit, then take no more; the queue is kept. With `args.jobId`, stop that job at a safe point and hold its units. */
     readonly STOP: "stop";
     /** Halt at the next safe point, holding the current unit; nothing new starts. */
     readonly PAUSE: "pause";

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

@@ -77,7 +77,7 @@ exports.OP = {
     CANCEL: 'cancel',
     /** Take work: begin or continue the queue. */
     START: 'start',
-    /** Finish the current unit, then take no more; the queue is kept. */
+    /** Finish the current unit, then take no more; the queue is kept. With `args.jobId`, stop that job at a safe point and hold its units. */
     STOP: 'stop',
     /** Halt at the next safe point, holding the current unit; nothing new starts. */
     PAUSE: 'pause',

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

@@ -35,7 +35,7 @@ const ENVELOPE = shape({
 });
 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.PRESENCE]: shape({ online: BOOL, software: STR, sessionId: STR, reason: STR }, ['software', 'sessionId', 'reason']),
     [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 }) },
@@ -60,7 +60,7 @@ const BODY = {
     }),
     [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.REPLY]: shape({ cmdId: STR, status: oneOf(constants_1.REPLY_STATUS), reason: STR, code: STR }, ['code']),
     [topics_1.MESSAGE_KIND.REPORT]: { type: 'object' },
 };
 const ajv = new ajv_1.default({ allErrors: true, strict: false });

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

@@ -1,5 +1,5 @@
 /**
- * The machine broker (Mosquitto), rendered from the line. Machines speak
+ * The machine broker (Mosquitto), rendered from its lines. 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
@@ -7,7 +7,7 @@
  * NATS, where JetStream keeps them.
  */
 import { type LineCodec } from '../protocol/codec';
-import { type LineDef } from '../line';
+import { type Lines } from './site-conf';
 export interface MosquittoConfOptions {
     root: string;
     /** Certificate directory as the broker sees it. */
@@ -17,11 +17,12 @@ export interface MosquittoConfOptions {
     aclFile: string;
     maxPacketBytes?: number;
 }
-export declare function renderMosquittoConf(line: LineDef, opts: MosquittoConfOptions): string;
+/** The broker for one line or several: one listener, one bridge per line. */
+export declare function renderMosquittoConf(lines: Lines, 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;
+export declare function renderMosquittoAcl(lines: Lines, codec: Pick<LineCodec, 'root' | 'channels' | 'topicFor'>): string;

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

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * The machine broker (Mosquitto), rendered from the line. Machines speak
+ * The machine broker (Mosquitto), rendered from its lines. 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
@@ -14,7 +14,26 @@ const envelope_1 = require("../protocol/envelope");
 const codec_1 = require("../protocol/codec");
 const line_1 = require("../line");
 const site_conf_1 = require("./site-conf");
-function renderMosquittoConf(line, opts) {
+/** One bridge connection per line, carrying the line's topics out to the site NATS. */
+function bridgeBlock(line, opts) {
+    return `connection ${line.siteId}-${line.lineId}-site-nats
+address ${opts.siteNats}
+bridge_protocol_version mqttv311
+bridge_cafile ${opts.certDir}/ca.pem
+bridge_certfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.pem
+bridge_keyfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.key
+remote_clientid ${(0, site_conf_1.bridgeId)(line)}
+cleansession false
+try_private false
+notifications false
+topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
+`;
+}
+/** The broker for one line or several: one listener, one bridge per line. */
+function renderMosquittoConf(lines, opts) {
+    const list = (0, site_conf_1.linesOf)(lines);
+    if (!list.length)
+        throw new Error('renderMosquittoConf needs at least one line');
     return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
 persistence true
 persistence_location /mosquitto/data/
@@ -32,18 +51,7 @@ use_identity_as_username true
 acl_file ${opts.aclFile}
 max_packet_size ${opts.maxPacketBytes ?? 262_144}
 
-connection ${line.siteId}-${line.lineId}-site-nats
-address ${opts.siteNats}
-bridge_protocol_version mqttv311
-bridge_cafile ${opts.certDir}/ca.pem
-bridge_certfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.pem
-bridge_keyfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.key
-remote_clientid ${(0, site_conf_1.bridgeId)(line)}
-cleansession false
-try_private false
-notifications false
-topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
-`;
+${list.map((line) => bridgeBlock(line, opts)).join('\n')}`;
 }
 /**
  * The codec's channels decide the topics: a machine writes its events and telemetry and reads its commands.
@@ -51,7 +59,14 @@ topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
  * the channels under its own name (%u), so its certificate's common name must be its address. On a line
  * that also declares addresses, a certificate named for a declared address is denied that station's channels.
  */
-function renderMosquittoAcl(line, codec) {
+function renderMosquittoAcl(lines, codec) {
+    const list = (0, site_conf_1.linesOf)(lines);
+    if (!list.length)
+        throw new Error('renderMosquittoAcl needs at least one line');
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${list.map((line) => aclRules(line, codec)).join('\n\n')}\n`;
+}
+/** One line's rules: its stations, its controller, and the shadows a learning line needs. */
+function aclRules(line, codec) {
     const { siteId, lineId } = line;
     const { events, telemetry, commands } = codec.channels;
     const own = (address, channels) => channels.map((c) => (0, codec_1.topicOf)(codec, { siteId, lineId, address }, c));
@@ -70,7 +85,7 @@ function renderMosquittoAcl(line, codec) {
         ...commands.map((c) => `topic write ${(0, codec_1.topicOf)(codec, { siteId, lineId }, c)}`),
         `topic read ${codec.root}/${siteId}/${lineId}/#`,
     ].join('\n');
-    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${[...learned, ...shadows, ...machines, controller].join('\n\n')}\n`;
+    return [...learned, ...shadows, ...machines, controller].join('\n\n');
 }
 /** Deny a declared station's channels to a certificate named for its address, which the patterns would grant. */
 function shadowRules(line, address, topics) {

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

@@ -1,5 +1,5 @@
 /**
- * The site's NATS server, rendered from the line. It runs JetStream and an
+ * The site's NATS server, rendered from its lines. It runs JetStream and an
  * MQTT listener that only the machine broker's bridge logs in to (by client
  * certificate; the CN is its user, and it may publish only under the line's
  * topics). The gateway logs in by password and may only keep and read the
@@ -20,4 +20,11 @@ export interface SiteConfOptions {
 export declare function bridgeId(line: LineDef): string;
 /** What the gateway may publish: its streams' and its consumer's JetStream requests and acks, never a machine subject. */
 export declare function gatewayPublish(line: LineDef): string[];
-export declare function renderSiteConf(line: LineDef, opts: SiteConfOptions): string;
+/** One line, or every line the site runs. */
+export type Lines = LineDef | LineDef[];
+export declare function linesOf(lines: Lines): LineDef[];
+/**
+ * The site NATS for one line or several: one bridge user per line, one
+ * gateway user allowed every line's streams and subjects.
+ */
+export declare function renderSiteConf(lines: Lines, opts: SiteConfOptions): string;