@hotmeshio/long-tail 0.27.0 → 0.28.1

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

@@ -10,9 +10,14 @@ export declare function getFileMetadata(input: {
 export declare function deleteFile(input: {
     filePath: string;
 }): Promise<LTApiResult>;
+/**
+ * Stores the bytes with their SHA-256. A caller that names the digest it
+ * expects gets 422 when the bytes received differ, and nothing is stored.
+ */
 export declare function uploadFile(input: {
     path: string;
     buffer: Buffer;
+    sha256?: string;
 }): Promise<LTApiResult>;
 export declare function generateSignedUrl(input: {
     filePath: string;

package/build/api/files.js

@@ -5,6 +5,7 @@ exports.getFileMetadata = getFileMetadata;
 exports.deleteFile = deleteFile;
 exports.uploadFile = uploadFile;
 exports.generateSignedUrl = generateSignedUrl;
+const crypto_1 = require("crypto");
 const storage_1 = require("../lib/storage");
 const mime_1 = require("../lib/storage/mime");
 const publish_1 = require("../lib/events/publish");
@@ -46,9 +47,25 @@ async function deleteFile(input) {
         return { status: 500, error: err.message };
     }
 }
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+/**
+ * Stores the bytes with their SHA-256. A caller that names the digest it
+ * expects gets 422 when the bytes received differ, and nothing is stored.
+ */
 async function uploadFile(input) {
+    if (input.sha256 !== undefined && !SHA256_HEX.test(input.sha256)) {
+        return { status: 400, error: 'sha256 must be 64 hex characters' };
+    }
+    const sha256 = (0, crypto_1.createHash)('sha256').update(input.buffer).digest('hex');
+    if (input.sha256 && input.sha256.toLowerCase() !== sha256) {
+        return {
+            status: 422,
+            error: 'sha256 does not match the bytes received',
+            data: { error: 'sha256 does not match the bytes received', path: input.path, expected: input.sha256.toLowerCase(), actual: sha256 },
+        };
+    }
     try {
-        const result = await (0, storage_1.getStorageBackend)().write(input.path, input.buffer);
+        const result = await (0, storage_1.getStorageBackend)().write(input.path, input.buffer, { sha256 });
         const contentType = (0, mime_1.mimeFromPath)(input.path);
         (0, publish_1.publishFileEvent)({
             type: 'file.stored',
@@ -58,7 +75,7 @@ async function uploadFile(input) {
         });
         return {
             status: 200,
-            data: { path: input.path, size: result.size, content_type: contentType },
+            data: { path: input.path, size: result.size, content_type: contentType, sha256 },
         };
     }
     catch (err) {

package/build/api/knowledge.d.ts

@@ -14,7 +14,8 @@ export declare function getEntry(input: {
 export declare function getEntryVersion(input: {
     domain: string;
     key: string;
-    version: number;
+    /** An edition number, or the label an edition carries. */
+    version: number | string;
 }): Promise<LTApiResult>;
 export declare function listEntryVersions(input: {
     domain: string;
@@ -26,6 +27,7 @@ export declare function storeEntry(input: {
     data: Record<string, any>;
     tags?: string[];
     replace?: boolean;
+    label?: string;
 }): Promise<LTApiResult>;
 export declare function setField(input: {
     domain: string;

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/db/schemas/042_knowledge_edition_labels.sql

@@ -0,0 +1,9 @@
+-- An edition may carry a label: a name a lookup ref pins instead of the
+-- version number (a catalog revision, say). A label names one edition of an
+-- entry; editions without one are reached by number or as current.
+ALTER TABLE lt_knowledge_versions
+  ADD COLUMN IF NOT EXISTS label TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS lt_knowledge_versions_label_idx
+  ON lt_knowledge_versions (domain, key, label)
+  WHERE label IS NOT NULL;

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}. */
@@ -32,6 +35,7 @@ export declare function controllerId(line: LineDef): string;
 export declare function stationRole(process: string): string;
 export declare const DEFAULT_EXIT_ROLE = "line-exit";
 export declare const DEFAULT_OPERATOR_ROLE = "line-operator";
+export declare const DEFAULT_QUALITY_ROLE = "line-quality";
 /** 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. */
@@ -42,3 +46,5 @@ export declare function exitRole(line: LineDef): string;
 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;
+/** The role of the people who decide units a machine finished on hold: release, rework or scrap. */
+export declare function qualityRole(line: LineDef): string;

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.DEFAULT_QUALITY_ROLE = 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;
@@ -18,6 +20,7 @@ exports.stationRoles = stationRoles;
 exports.exitRole = exitRole;
 exports.receiverRoles = receiverRoles;
 exports.operatorRole = operatorRole;
+exports.qualityRole = qualityRole;
 const fs_1 = require("fs");
 const protocol_1 = require("./protocol");
 /** How a line knows its machines' addresses (`LineDef.addressing`). */
@@ -68,6 +71,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 } : {}) };
@@ -92,6 +110,7 @@ function stationRole(process) {
 }
 exports.DEFAULT_EXIT_ROLE = 'line-exit';
 exports.DEFAULT_OPERATOR_ROLE = 'line-operator';
+exports.DEFAULT_QUALITY_ROLE = 'line-quality';
 /** The Long Tail role a machine resolves handoffs under. */
 function machineRole(def) {
     return def.role ?? stationRole(def.process);
@@ -112,3 +131,7 @@ function receiverRoles(line) {
 function operatorRole(line) {
     return line.roles?.operator ?? exports.DEFAULT_OPERATOR_ROLE;
 }
+/** The role of the people who decide units a machine finished on hold: release, rework or scrap. */
+function qualityRole(line) {
+    return line.roles?.quality ?? exports.DEFAULT_QUALITY_ROLE;
+}

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

@@ -20,6 +20,12 @@ export interface MachineCommand {
     attempt?: number;
     /** The command may have reached the machine before: sent earlier, or its row predates this gateway's takeover. */
     retry?: boolean;
+    /**
+     * When the command was issued, ISO 8601: the same on every send of this `cmdId`, by this gateway or the
+     * next, so a protocol that stamps a time repeats the first attempt. A dispatch or a command row takes the
+     * start of its validity round; any other command the time of its first send.
+     */
+    issuedAt?: string;
 }
 /** MQTT filters under each machine's topic, e.g. `job` or `alarm/+`. */
 export interface CodecChannels {
@@ -71,6 +77,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 +93,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' };
@@ -74,7 +83,7 @@ function genericCodec(opts) {
             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)) }];
+            return [{ topic: (0, topics_1.machineTopic)(opts.root, ident, constants_1.CHANNEL.CMD), payload: JSON.stringify((0, envelope_1.buildEnvelope)(ident, command, { at: command.issuedAt })) }];
         },
     };
 }

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.d.ts

@@ -17,3 +17,5 @@ export interface Inspection {
 }
 /** Validate one message. `retained` is the publisher's flag when the transport reports it. */
 export declare function inspectMessage(root: string, topic: string, raw: string | Buffer, retained?: boolean): Inspection;
+/** A receiver's report that it could read no id at all: a transfer failure on the read, naming no unit and no carrier. */
+export declare function isUnreadableRead(b: Record<string, any>): boolean;