@hotmeshio/long-tail 0.27.0 → 0.28.0

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

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * 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
@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bridgeId = bridgeId;
 exports.gatewayPublish = gatewayPublish;
+exports.linesOf = linesOf;
 exports.renderSiteConf = renderSiteConf;
 const line_1 = require("../line");
 const protocol_1 = require("../protocol");
@@ -25,18 +26,36 @@ function bridgeId(line) {
 function gatewayPublish(line) {
     return (0, permissions_1.jsPermissions)({ streams: Object.values(streams_1.LINE_STREAM), durable: `${(0, line_1.controllerId)(line)}-events` }).publish;
 }
-function renderSiteConf(line, opts) {
-    const base = (0, protocol_1.toSubject)(`${opts.root}/${line.siteId}/${line.lineId}`);
-    const bridge = [
+function linesOf(lines) {
+    return Array.isArray(lines) ? lines : [lines];
+}
+/** The server's name: the line for one line, the site when every line shares it, `site` otherwise. */
+function serverName(lines) {
+    if (lines.length === 1)
+        return `${lines[0].siteId}-${lines[0].lineId}`;
+    const sites = new Set(lines.map((l) => l.siteId));
+    return sites.size === 1 ? lines[0].siteId : 'site';
+}
+/**
+ * The site NATS for one line or several: one bridge user per line, one
+ * gateway user allowed every line's streams and subjects.
+ */
+function renderSiteConf(lines, opts) {
+    const list = linesOf(lines);
+    if (!list.length)
+        throw new Error('renderSiteConf needs at least one line');
+    const baseOf = (line) => (0, protocol_1.toSubject)(`${opts.root}/${line.siteId}/${line.lineId}`);
+    const bridge = list.map((line) => [
         `    { user: ${q(`CN=${bridgeId(line)}`)}, allowed_connection_types: ["MQTT"],`,
-        `      permissions: { publish: [${q(`${base}.>`)}], subscribe: { deny: [">"] } } }`,
-    ].join('\n');
+        `      permissions: { publish: [${q(`${baseOf(line)}.>`)}], subscribe: { deny: [">"] } } }`,
+    ].join('\n')).join('\n');
+    const publish = [...new Set(list.flatMap((line) => gatewayPublish(line)))];
     const gateway = [
         `    { user: ${q(opts.gatewayUser)}, password: ${q(opts.gatewayPassword)}, allowed_connection_types: ["STANDARD"],`,
-        `      permissions: { publish: ${q(gatewayPublish(line))}, subscribe: ${q(['_INBOX.>', `${base}.>`])} } }`,
+        `      permissions: { publish: ${q(publish)}, subscribe: ${q(['_INBOX.>', ...list.map((line) => `${baseOf(line)}.>`)])} } }`,
     ].join('\n');
     return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
-server_name: ${q(`${line.siteId}-${line.lineId}`)}
+server_name: ${q(serverName(list))}
 port: 4222
 http: 8222
 jetstream { store_dir: ${q(opts.storeDir)} }

package/build/lib/machines/transport/callback-feed.d.ts

@@ -14,5 +14,6 @@ export declare class CallbackEscalationFeed implements EscalationFeed {
     constructor(adapter: CallbackEventAdapter, nakDelayMs?: number);
     connect(): Promise<void>;
     consume(handler: (event: EscalationEvent) => Promise<MachineDisposition>): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }

package/build/lib/machines/transport/callback-feed.js

@@ -23,9 +23,12 @@ class CallbackEscalationFeed {
                 void this.redelivery.deliver(() => handler(event));
         });
     }
-    async close() {
+    async unsubscribe() {
         this.off?.();
         await this.redelivery.stop();
     }
+    async close() {
+        await this.unsubscribe();
+    }
 }
 exports.CallbackEscalationFeed = CallbackEscalationFeed;

package/build/lib/machines/transport/memory.d.ts

@@ -26,6 +26,7 @@ export declare class MemoryMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }
 export declare class MemoryEscalationFeed implements EscalationFeed {
@@ -36,5 +37,6 @@ export declare class MemoryEscalationFeed implements EscalationFeed {
     emit(body: Record<string, any>): void;
     connect(): Promise<void>;
     consume(handler: (event: EscalationEvent) => Promise<Disposition>): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }

package/build/lib/machines/transport/memory.js

@@ -50,6 +50,9 @@ class MemoryMachineBus {
     async retained(filter) {
         return this.broker.retained(filter);
     }
+    async unsubscribe() {
+        this.broker.detach(this.durableName);
+    }
     async close() {
         this.broker.detach(this.durableName);
     }
@@ -72,6 +75,9 @@ class MemoryEscalationFeed {
             return event ? handler(event) : delivery_1.DISPOSITION.TERM;
         });
     }
+    async unsubscribe() {
+        this.broker.detach(this.durableName);
+    }
     async close() {
         this.broker.detach(this.durableName);
     }

package/build/lib/machines/transport/mqtt-bus.d.ts

@@ -19,6 +19,8 @@ export declare class MqttMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    /** Stops delivery in this process; the persistent session keeps its subscription, so messages queue for the next gateway. */
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
     private connected;
 }

package/build/lib/machines/transport/mqtt-bus.js

@@ -30,6 +30,10 @@ class MqttMachineBus {
     retained(filter) {
         return this.connected().retained(filter);
     }
+    /** Stops delivery in this process; the persistent session keeps its subscription, so messages queue for the next gateway. */
+    async unsubscribe() {
+        await this.redelivery.stop();
+    }
     async close() {
         await this.redelivery.stop();
         await this.session?.close(true);

package/build/lib/machines/transport/nats-bus.d.ts

@@ -31,6 +31,7 @@ export declare class NatsMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
     private stream;
 }

package/build/lib/machines/transport/nats-bus.js

@@ -34,6 +34,9 @@ class NatsMachineBus {
     retained(filter) {
         return this.stream().retained(filter);
     }
+    async unsubscribe() {
+        await this.bus?.unsubscribe();
+    }
     async close() {
         await this.bus?.close();
         await this.provider.disconnect();

package/build/lib/machines/transport/nats-feed.d.ts

@@ -21,6 +21,7 @@ export declare class CoreEscalationFeed implements EscalationFeed {
     constructor(opts: CoreFeedOptions);
     connect(): Promise<void>;
     consume(handler: Handler): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }
 export {};

package/build/lib/machines/transport/nats-feed.js

@@ -40,9 +40,12 @@ class CoreEscalationFeed {
             },
         });
     }
-    async close() {
+    async unsubscribe() {
         this.sub?.unsubscribe();
         await this.redelivery.stop();
+    }
+    async close() {
+        await this.unsubscribe();
         await this.nc?.drain();
     }
 }

package/build/lib/machines/transport/pubsub-feed.d.ts

@@ -13,5 +13,6 @@ export declare class PubSubEscalationFeed implements EscalationFeed {
     constructor(pubsub: LTPubSub, nakDelayMs?: number);
     connect(): Promise<void>;
     consume(handler: (event: EscalationEvent) => Promise<Disposition>): Promise<void>;
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
 }

package/build/lib/machines/transport/pubsub-feed.js

@@ -31,9 +31,12 @@ class PubSubEscalationFeed {
                 void this.redelivery.deliver(() => handler(event));
         });
     }
-    async close() {
+    async unsubscribe() {
         await this.sub?.close();
         await this.redelivery.stop();
     }
+    async close() {
+        await this.unsubscribe();
+    }
 }
 exports.PubSubEscalationFeed = PubSubEscalationFeed;

package/build/lib/machines/transport/stream-bus.d.ts

@@ -35,6 +35,8 @@ export declare class StreamMachineBus implements MachineBus {
         retain?: boolean;
     }): Promise<void>;
     retained(filter: string): Promise<InboundMessage[]>;
+    /** Stops the consumer and the live subscriptions; the MQTT session stays open for commands and receipts. */
+    unsubscribe(): Promise<void>;
     close(): Promise<void>;
     private mqtt;
 }

package/build/lib/machines/transport/stream-bus.js

@@ -42,10 +42,14 @@ class StreamMachineBus {
     retained(filter) {
         return this.mqtt().retained(filter);
     }
-    async close() {
+    /** Stops the consumer and the live subscriptions; the MQTT session stays open for commands and receipts. */
+    async unsubscribe() {
         for (const sub of this.subs.splice(0))
             await sub.close();
         await this.queue.drained();
+    }
+    async close() {
+        await this.unsubscribe();
         await this.session?.close(true);
     }
     mqtt() {

package/build/modules/machines.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The running machine surface, for settings and the machines API. Set by
+ * start() when the config declares lines; absent otherwise, so a deployment
+ * without machines serves no lines and no Lines view.
+ */
+import type { LineSurface } from '../services/machines/surface';
+export declare function registerMachineSurface(next: LineSurface | null): void;
+export declare function getMachineSurface(): LineSurface | null;

package/build/modules/machines.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * The running machine surface, for settings and the machines API. Set by
+ * start() when the config declares lines; absent otherwise, so a deployment
+ * without machines serves no lines and no Lines view.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMachineSurface = registerMachineSurface;
+exports.getMachineSurface = getMachineSurface;
+let surface = null;
+function registerMachineSurface(next) {
+    surface = next;
+}
+function getMachineSurface() {
+    return surface;
+}

package/build/routes/index.js

@@ -40,6 +40,7 @@ const nats_credentials_1 = __importDefault(require("./nats-credentials"));
 const scan_codes_1 = __importDefault(require("./scan-codes"));
 const domain_1 = __importDefault(require("./domain"));
 const announcements_1 = __importDefault(require("./announcements"));
+const machines_1 = __importDefault(require("./machines"));
 const router = (0, http_1.Router)();
 // Public routes (no auth required — they handle their own auth)
 router.use('/auth', auth_2.default);
@@ -80,6 +81,7 @@ router.use('/topics', topics_1.default);
 router.use('/scan-codes', scan_codes_1.default);
 router.use('/domain', domain_1.default);
 router.use('/announcements', announcements_1.default);
+router.use('/machines', machines_1.default);
 const overview_1 = __importDefault(require("./overview"));
 router.use('/overview', overview_1.default);
 const diagnostics_1 = __importDefault(require("./diagnostics"));

package/build/routes/machines.d.ts

@@ -0,0 +1,2 @@
+declare const router: import("express-serve-static-core").Router;
+export default router;

package/build/routes/machines.js

@@ -0,0 +1,220 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const http_1 = require("../lib/http");
+const escalationsApi = __importStar(require("../api/escalations"));
+const auth_1 = require("../modules/auth");
+const machines_1 = require("../modules/machines");
+const commands_1 = require("../services/machines/commands");
+const registry_1 = require("../services/machines/registry");
+const registry_sync_1 = require("../services/machines/registry-sync");
+const line_index_1 = require("../services/machines/line-index");
+const topics_1 = require("../lib/machines/protocol/topics");
+const router = (0, http_1.Router)();
+/**
+ * The machine surface for the dashboard's Lines view. Reads and the dry run
+ * take the ops tier (superadmin, admin type, or engineer); declaring and
+ * retiring a line takes an administrator. A command is a row parked on the
+ * machine's role as the caller, so that role's write access decides, exactly
+ * as it does for any row created through the API.
+ */
+const NO_LINES = 'no machine lines are declared';
+const NOT_LEADING = 'this replica is not leading the line';
+function lineOf(req) {
+    const surface = (0, machines_1.getMachineSurface)();
+    const siteId = String(req.params.siteId);
+    const lineId = String(req.params.lineId);
+    const line = surface?.findLine(siteId, lineId);
+    return { surface, siteId, lineId, line };
+}
+const SORTS = new Set(['attention', 'site', 'updated']);
+/** The longest search a person types; anything past it is cut, never an error. */
+const QUERY_MAX_CHARS = 200;
+function queryString(v) {
+    return typeof v === 'string' && v.trim() ? v.trim().slice(0, QUERY_MAX_CHARS) : undefined;
+}
+/** The line a path names, when both tokens could name a line at all. */
+function pathLine(req) {
+    const siteId = req.params.siteId;
+    const lineId = req.params.lineId;
+    return (0, topics_1.isTopicLevel)(siteId) && (0, topics_1.isTopicLevel)(lineId) ? { siteId, lineId } : null;
+}
+function queryBoolean(v) {
+    return v === 'true' ? true : v === 'false' ? false : undefined;
+}
+function queryInt(v) {
+    const n = typeof v === 'string' ? Number(v) : NaN;
+    return Number.isFinite(n) ? n : undefined;
+}
+router.get('/lines', auth_1.requireRoleManager, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const sort = queryString(req.query.sort);
+    if (sort && !SORTS.has(sort)) {
+        res.status(400).json({ error: `sort must be one of ${[...SORTS].join(', ')}` });
+        return;
+    }
+    const query = {
+        q: queryString(req.query.q), site: queryString(req.query.site), attention: queryBoolean(req.query.attention),
+        sort: sort, limit: queryInt(req.query.limit), offset: queryInt(req.query.offset),
+    };
+    const [page, sites] = await Promise.all([(0, registry_1.listLines)(query), (0, registry_1.listSites)()]);
+    const body = {
+        lines: page.lines.map((record) => (0, line_index_1.toLineIndexRow)(surface, record)),
+        total: page.total, sites, limit: page.limit, offset: page.offset,
+    };
+    res.status(200).json(body);
+});
+router.put('/lines/:siteId/:lineId', auth_1.requireAdmin, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const named = pathLine(req);
+    if (!named) {
+        res.status(400).json({ error: 'siteId and lineId must be topic levels' });
+        return;
+    }
+    const { siteId, lineId } = named;
+    const definition = req.body?.definition;
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+        res.status(400).json({ error: 'definition is required' });
+        return;
+    }
+    if (definition.siteId !== siteId || definition.lineId !== lineId) {
+        res.status(400).json({ error: `definition must be for ${siteId}/${lineId}` });
+        return;
+    }
+    const version = req.body?.version;
+    if (version !== undefined && !(Number.isInteger(version) && version >= 1)) {
+        res.status(400).json({ error: 'version must be a whole number of at least 1' });
+        return;
+    }
+    try {
+        const record = await (0, registry_sync_1.declareLine)(surface, definition, version);
+        const stored = (await (0, registry_1.getLineWithHealth)(siteId, lineId)) ?? { ...record, health: (0, line_index_1.emptyLineHealth)(record.definition.machines.length) };
+        res.status(200).json({ line: (0, line_index_1.toLineIndexRow)(surface, stored) });
+    }
+    catch (err) {
+        if (err instanceof registry_1.LineVersionConflict) {
+            res.status(409).json({ error: err.message });
+            return;
+        }
+        res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+    }
+});
+router.delete('/lines/:siteId/:lineId', auth_1.requireAdmin, async (req, res) => {
+    const surface = (0, machines_1.getMachineSurface)();
+    if (!surface) {
+        res.status(404).json({ error: NO_LINES });
+        return;
+    }
+    const named = pathLine(req);
+    if (!named) {
+        res.status(404).json({ error: 'no such line' });
+        return;
+    }
+    const { siteId, lineId } = named;
+    const record = await (0, registry_sync_1.retireLine)(surface, siteId, lineId);
+    if (!record) {
+        res.status(404).json({ error: `no line ${siteId}/${lineId}` });
+        return;
+    }
+    res.status(204).end();
+});
+router.get('/lines/:siteId/:lineId', auth_1.requireRoleManager, (req, res) => {
+    const { surface, siteId, lineId, line } = lineOf(req);
+    if (!surface || !line) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const body = {
+        ...(surface.describeLine(siteId, lineId) ?? { siteId, lineId, leading: false }),
+        summary: (0, line_index_1.lineSummaryOf)(surface, siteId, lineId, line),
+    };
+    res.status(200).json(body);
+});
+router.post('/lines/:siteId/:lineId/inspect', auth_1.requireRoleManager, (req, res) => {
+    const { surface, siteId, lineId, line } = lineOf(req);
+    if (!surface || !line) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const topic = req.body?.topic;
+    if (typeof topic !== 'string' || !topic) {
+        res.status(400).json({ error: 'topic is required' });
+        return;
+    }
+    const result = surface.inspect(siteId, lineId, { topic, payload: (0, line_index_1.wirePayloadOf)(req.body?.payload), retained: req.body?.retained === true });
+    if (!result) {
+        res.status(409).json({ error: NOT_LEADING });
+        return;
+    }
+    res.status(200).json(result);
+});
+router.post('/lines/:siteId/:lineId/machines/:machineId/commands', async (req, res) => {
+    const { surface, siteId, lineId, line } = lineOf(req);
+    if (!surface || !line) {
+        res.status(404).json({ error: surface ? `no line ${siteId}/${lineId}` : NO_LINES });
+        return;
+    }
+    const machineId = String(req.params.machineId);
+    if (!line.machines.some((m) => m.machineId === machineId)) {
+        res.status(404).json({ error: `no machine ${machineId} on ${siteId}/${lineId}` });
+        return;
+    }
+    const op = req.body?.op;
+    const ops = surface.commandOps(siteId, lineId);
+    if (typeof op !== 'string' || !ops.includes(op)) {
+        res.status(400).json({ error: `op must be one of ${ops.join(', ')}` });
+        return;
+    }
+    const args = req.body?.args;
+    if (args !== undefined && (!args || typeof args !== 'object' || Array.isArray(args))) {
+        res.status(400).json({ error: 'args must be an object' });
+        return;
+    }
+    const result = await escalationsApi.createEscalation((0, commands_1.commandRow)((0, commands_1.commandTarget)(line, machineId), op, args ?? {}), req.auth);
+    if (result.status !== 201) {
+        res.status(result.status).json({ error: result.error });
+        return;
+    }
+    res.status(201).json({ rowId: result.data.id });
+});
+exports.default = router;

package/build/services/machines/commands.d.ts

@@ -1,11 +1,11 @@
 /**
  * Commands as rows. A host asks a machine to start, stop, pause, resume,
- * change over or cancel a job by parking a machine-command row on the machine's role, from a
- * workflow step or through the API, the same way it asks a person for
+ * change over, cancel a job, report a snapshot, or do anything its codec
+ * declares (`rowOps`), by parking a machine-command row on the machine's role,
+ * from a workflow step or through the API, the same way it asks a person for
  * anything. The gateway sends the command and resolves the row with the
  * machine's reply (CommandResolution), so the step reads the outcome as data.
  */
-import type { Op } from '../../lib/machines/protocol';
 import { type LineDef } from '../../lib/machines/line';
 import { type CommandFacets } from './contracts';
 /** Where a command goes: the machine and the role its rows land on. */
@@ -17,10 +17,10 @@ export interface CommandTarget {
 }
 export declare function commandTarget(line: LineDef, machineId: string): CommandTarget;
 /** The row that asks a machine for `op`: pass it to conditional(), or create it through the API. */
-export declare function commandRow(target: CommandTarget, op: Op, args?: Record<string, unknown>): {
+export declare function commandRow(target: CommandTarget, op: string, args?: Record<string, unknown>): {
     role: string;
     type: "machine-command";
-    subtype: Op;
+    subtype: string;
     description: string;
     priority: number;
     metadata: Record<string, unknown>;

package/build/services/machines/commands.js

@@ -1,8 +1,9 @@
 "use strict";
 /**
  * Commands as rows. A host asks a machine to start, stop, pause, resume,
- * change over or cancel a job by parking a machine-command row on the machine's role, from a
- * workflow step or through the API, the same way it asks a person for
+ * change over, cancel a job, report a snapshot, or do anything its codec
+ * declares (`rowOps`), by parking a machine-command row on the machine's role,
+ * from a workflow step or through the API, the same way it asks a person for
  * anything. The gateway sends the command and resolves the row with the
  * machine's reply (CommandResolution), so the step reads the outcome as data.
  */

package/build/services/machines/config.d.ts

@@ -29,7 +29,6 @@ export interface MachineLineConfig {
     mqtt?: MqttEndpoint;
     replyTimeoutMs: number;
     dispatchAttempts: number;
-    handoffTimeout: string;
     offlineDebounceMs: number;
     /** A connected machine silent this long gets a quiet row; 0 turns the check off. */
     quietMs: number;
@@ -41,6 +40,8 @@ export interface MachineLineConfig {
     lifecycle: boolean;
     /** With lifecycle notes, progress is noted each time it crosses this many percent; 0 notes none. */
     progressStep: number;
+    /** Telemetry messages are published as wire events too; off by default, since they are read live and many. */
+    wireTelemetry: boolean;
     ltBaseUrl: string;
 }
 type Env = Record<string, string | undefined>;

package/build/services/machines/config.js

@@ -68,13 +68,13 @@ function loadMachineLineConfig(env = process.env) {
         lineConfigPath: env.MACHINE_LINE_CONFIG || undefined,
         replyTimeoutMs: int(env, 'MACHINE_REPLY_TIMEOUT_MS', protocol_1.REPLY_DEADLINE_MS),
         dispatchAttempts: Math.max(1, int(env, 'MACHINE_DISPATCH_ATTEMPTS', 3)),
-        handoffTimeout: env.MACHINE_HANDOFF_TIMEOUT ?? '10m',
         offlineDebounceMs: int(env, 'MACHINE_OFFLINE_DEBOUNCE_MS', 15_000),
         quietMs: int(env, 'MACHINE_QUIET_MS', 90_000),
         dispatchTtlMs: int(env, 'MACHINE_DISPATCH_TTL_MS', 600_000),
         receiptDelayMs: int(env, 'MACHINE_RECEIPT_DELAY_MS', 250),
         lifecycle: oneOf('MACHINE_LIFECYCLE', env.MACHINE_LIFECYCLE || SWITCH.OFF, Object.values(SWITCH)) === SWITCH.ON,
         progressStep: percentStep(env, 'MACHINE_PROGRESS_STEP', 25),
+        wireTelemetry: oneOf('MACHINE_WIRE_TELEMETRY', env.MACHINE_WIRE_TELEMETRY || SWITCH.OFF, Object.values(SWITCH)) === SWITCH.ON,
         ltBaseUrl: env.LT_BASE_URL ?? 'http://localhost:3000',
     };
     if (transport === exports.MACHINE_TRANSPORT.NATS) {

package/build/services/machines/contracts.d.ts

@@ -43,6 +43,8 @@ export interface HandoffUnit {
     artifacts?: ArtifactRef[];
     /** Parameters for this unit alone, sent to the machine as given. */
     parameters?: Record<string, unknown>;
+    /** The host's references for this unit, by name; sent to the machine as given and searchable on the row. */
+    refs?: Record<string, string>;
 }
 /** Metadata on a handoff row. Everything a dispatch needs rides here. */
 export interface HandoffFacets {
@@ -66,6 +68,8 @@ export interface HandoffFacets {
     attempt: number;
     /** Parameters for the job, sent to the machine as given; what they mean is between the host and its codec. */
     parameters?: Record<string, unknown>;
+    /** The host's references for the job, by name (an order, a batch, a ticket); sent to the machine as given and searchable on the row. */
+    refs?: Record<string, string>;
 }
 /**
  * Items a handoff row accumulates, one per unit: the sender's finished-job
@@ -151,8 +155,12 @@ export interface HandoffResolution {
     /** The machine that reported the error, when it is not the one resolving. */
     reportedBy?: string;
     errorCode?: HandoffErrorCode;
+    /** On `sender-rejected`, how the sender finished the unit: reject, hold, scrap or rework. */
+    result?: string;
     reason?: string | null;
     detail?: string;
+    /** The machine's structured code for a refusal or failure, when its reply carried one. */
+    code?: string;
 }
 /** Decisions on line-operator rows: failed handoffs, alarms, dark machines, contested registrations. */
 export declare const DECISION: {
@@ -202,6 +210,8 @@ export interface CommandResolution {
     op: string;
     status: CommandStatus;
     reason?: string;
+    /** The machine's structured code for the outcome, when its reply carried one. */
+    code?: string;
 }
 /** A row's dispatch command in its validity round; a later round is a new command (gateway/pacing.ts dispatchWindow). */
 export declare const dispatchCommandId: (escalationId: string, round?: number) => string;

package/build/services/machines/gateway/actions.d.ts

@@ -78,6 +78,7 @@ export type Action =
     cmdId: string;
     status: string;
     reason: string;
+    code?: string;
 }
 /** A machine reported the jobs it holds: answers a status query in flight. */
  | {