@hotmeshio/long-tail 0.25.3 → 0.26.0

package/README.md

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

package/build/index.d.ts

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

package/build/index.js

@@ -37,11 +37,12 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishKnowledgeEvent = exports.publishAgentEvent = exports.publishWorkflowEvent = exports.publishActivityEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.seedConfigTopics = exports.seedSystemTopics = exports.TopicService = exports.displayGtin = exports.normalizeGtin = exports.isValidGtin = exports.assertValidScanIdentityRule = exports.assertValidScanSteps = exports.assertValidScanScheme = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.setAuthAdapter = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionalAccumulator = exports.conditionLT = exports.conditional = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.midnightTheme = exports.start = void 0;
-exports.LTExpressAdapter = exports.api = exports.KnowledgeApi = exports.resolveCredential = exports.mimeFromPath = exports.getStorageBackend = exports.listOAuthConnections = exports.getFreshAccessToken = exports.createClient = exports.CallbackEventAdapter = exports.builtinMcpServerFactories = exports.getSystemAgents = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = void 0;
+exports.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;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const midnight_1 = require("./themes/midnight");
 const start_1 = require("./start");
+const line_1 = require("./lib/machines/line");
 // ─── Package Exports ─────────────────────────────────────────────────────────
 var start_2 = require("./start");
 Object.defineProperty(exports, "start", { enumerable: true, get: function () { return start_2.start; } });
@@ -151,6 +152,7 @@ var credentials_1 = require("./services/iam/credentials");
 Object.defineProperty(exports, "resolveCredential", { enumerable: true, get: function () { return credentials_1.resolveCredential; } });
 exports.KnowledgeApi = __importStar(require("./api/knowledge"));
 exports.api = __importStar(require("./api"));
+exports.Machines = __importStar(require("./services/machines"));
 var express_1 = require("./adapters/express");
 Object.defineProperty(exports, "LTExpressAdapter", { enumerable: true, get: function () { return express_1.LTExpressAdapter; } });
 // ─── Server ──────────────────────────────────────────────────────────────────
@@ -252,6 +254,11 @@ async function main() {
         escalation: {
             strategy: 'mcp',
         },
+        // Machines resolve rows over MQTT when a line and a transport are configured
+        // (docker-compose.machines.yml sets both).
+        machines: process.env.MACHINE_TRANSPORT && process.env.MACHINE_LINE_CONFIG
+            ? { lines: [(0, line_1.loadLine)(process.env.MACHINE_LINE_CONFIG)] }
+            : undefined,
         branding: {
             ...(process.env.WHITE_LABEL ? { appName: process.env.WHITE_LABEL } : {}),
             // Midnight ships as a registered theme — the working proof that a

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

@@ -0,0 +1,5 @@
+export * from './protocol';
+export * from './transport';
+export * from './line';
+export * from './site/site-conf';
+export * from './site/mosquitto-conf';

package/build/lib/machines/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./protocol"), exports);
+__exportStar(require("./transport"), exports);
+__exportStar(require("./line"), exports);
+__exportStar(require("./site/site-conf"), exports);
+__exportStar(require("./site/mosquitto-conf"), exports);

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

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

package/build/lib/machines/line.js

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * The line protocol as JSON Schema plus the rules a schema cannot express.
+ * Known fields are checked; unknown fields are allowed, so a machine on a
+ * newer minor version can add fields without breaking older gateways. The
+ * gateway checks every inbound message; the tests check everything the mock sends.
+ */
+import { type Envelope } from './envelope';
+import { type ParsedTopic } from './topics';
+export interface Inspection {
+    parsed: ParsedTopic | null;
+    body: Envelope | null;
+    violations: string[];
+    /** Set by a codec whose machines await a receipt: the id to confirm once the gateway is done with the message. */
+    receiptId?: string;
+    /** The station the message says it comes from, when the wire names one apart from the address (a line that learns addresses). */
+    claim?: string;
+}
+/** Validate one message. `retained` is the publisher's flag when the transport reports it. */
+export declare function inspectMessage(root: string, topic: string, raw: string | Buffer, retained?: boolean): Inspection;