@hotmeshio/long-tail 0.26.0 → 0.28.0

package/build/services/machines/gateway/executor.js

@@ -3,7 +3,8 @@
  * Runs the planner's actions: escalation verbs through LineEscalations,
  * dispatches and commands through the Dispatcher, alarm and machine rows,
  * and the offline debounce. A verb that fails for real throws, so the message that
- * caused it is delivered again.
+ * caused it is delivered again. What ran comes back as wire actions, for the
+ * record of the message that caused it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Executor = void 0;
@@ -15,18 +16,29 @@ const escalations_1 = require("./escalations");
 const log_1 = require("./log");
 const dispatcher_1 = require("./dispatcher");
 const plan_shared_1 = require("./plan-shared");
+const state_1 = require("./state");
+const wire_1 = require("./wire");
 const NOT_FOUND = 404;
 const CONFLICT = 409;
+/** A verb's outcome as the wire records it: done, already done, or refused by Long Tail. */
+function outcomeOf(verb, rowId, result) {
+    const refused = result.outcome === escalations_1.VERB_OUTCOME.INVALID || result.status === NOT_FOUND || result.status === CONFLICT;
+    if (refused)
+        return { verb: 'refuse', rowId, detail: `${verb}: ${result.detail ?? result.outcome}` };
+    return { verb, rowId, ...(result.outcome === escalations_1.VERB_OUTCOME.ALREADY ? { detail: result.detail ?? 'already ended' } : {}) };
+}
 class Executor {
     constructor(d) {
         this.d = d;
         this.inflight = new Set();
         this.quietPending = new Set();
         this.timers = new Set();
+        this.stopped = false;
         this.dispatcher = new dispatcher_1.Dispatcher(d);
     }
     /** Dispatches and commands run detached so one slow reply never holds up the feed. */
     async apply(actions) {
+        const done = [];
         for (const action of actions) {
             if (action.kind === 'dispatch')
                 this.track(this.dispatcher.dispatch(action));
@@ -34,75 +46,110 @@ class Executor {
                 this.track(this.dispatcher.command(action));
             else if (action.kind === 'control')
                 this.track(this.dispatcher.control(action));
-            else
-                await this.run(action);
+            else {
+                done.push(...await this.run(action));
+                continue;
+            }
+            done.push((0, wire_1.plannedAction)(action));
         }
+        return done;
     }
     /** Resolves when every detached dispatch has finished. */
     async idle() {
         while (this.inflight.size)
             await Promise.all([...this.inflight]);
     }
+    /** Work still running sends nothing more and raises no row; the next leader takes it up from the message or the row. */
     stop() {
+        this.stopped = true;
         for (const t of this.timers)
             clearTimeout(t);
         this.timers.clear();
+        this.dispatcher.stop();
         this.d.replies.cancelAll();
     }
+    /** A row raised after stop() would be raised again by the next leader, so the message is nak'd instead. */
+    live() {
+        if (this.stopped)
+            throw new dispatcher_1.GatewayStopped();
+    }
     track(work) {
-        const tracked = work.catch((err) => this.d.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { error: String(err?.message ?? err) }))
+        const tracked = work.catch((err) => {
+            if (!(err instanceof dispatcher_1.GatewayStopped))
+                this.d.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { error: String(err?.message ?? err) });
+        })
             .finally(() => this.inflight.delete(tracked));
         this.inflight.add(tracked);
     }
     async run(a) {
         const { lt, state, replies } = this.d;
         switch (a.kind) {
-            case 'claim':
-                return this.check(a, await lt.claim(a.as, a.rowId));
+            case 'claim': {
+                const result = await lt.claim(a.as, a.rowId);
+                this.check(a, result);
+                return [outcomeOf('claim', a.rowId, result)];
+            }
             case 'accumulate':
                 return this.accumulate(a);
-            case 'resolve':
-                this.check(a, await lt.resolve(a.as, a.rowId, a.payload));
+            case 'resolve': {
+                const result = await lt.resolve(a.as, a.rowId, a.payload);
+                this.check(a, result);
                 state.close(a.rowId);
-                return;
+                return [outcomeOf('resolve', a.rowId, result)];
+            }
             case 'createAlarmRow':
-                return this.createAlarmRow(a);
+                return [{ verb: 'create-row', rowId: await this.createAlarmRow(a), detail: `${a.row.type} ${a.alarmId} at ${a.machineId}` }];
             case 'createRow': {
+                this.live();
                 const { id } = await lt.create(actions_1.CONTROLLER, a.row);
                 this.d.log.info(log_1.GATEWAY_LOG.VIOLATION_ROW, { row: id, type: a.row.type });
-                return;
+                return [{ verb: 'create-row', rowId: id, detail: a.row.type }];
             }
             case 'watchOffline':
-                return this.watchOffline(a.machineId);
+                this.watchOffline(a.machineId);
+                return [(0, wire_1.plannedAction)(a)];
             case 'settleReply':
-                if (!replies.settle({ cmdId: a.cmdId, status: a.status, reason: a.reason }))
-                    await this.lateReply(a);
-                return;
+                if (replies.settle({ cmdId: a.cmdId, status: a.status, reason: a.reason, ...(a.code ? { code: a.code } : {}) }))
+                    return [(0, wire_1.plannedAction)(a)];
+                return [{ verb: 'ack', detail: `late ${a.status} ${a.cmdId}` }, ...await this.lateReply(a)];
             case 'settleSnapshot':
                 replies.settleSnapshot(a.machineId, new Set(a.jobIds));
-                return;
+                return [(0, wire_1.plannedAction)(a)];
             case 'bindAddress':
                 await this.d.addresses.bind(a.machineId, a.address);
                 state.bindAddress(a.machineId, a.address);
                 this.d.log.info(log_1.GATEWAY_LOG.ADDRESS_BOUND, { machine: a.machineId, address: a.address, ...(a.by ? { approvedBy: a.by } : {}) });
-                return;
+                return [{ verb: 'ack', detail: `bound ${a.machineId} to ${a.address}` }];
             case 'refuseBinding':
                 this.d.log.warn(log_1.GATEWAY_LOG.ADDRESS_REFUSED, { machine: a.machineId, address: a.address, reason: a.reason });
+                return [(0, wire_1.plannedAction)(a)];
         }
     }
-    /** A dispatch's second reply: ready, or a failure to prepare that ends the handoff. */
+    /**
+     * A dispatch's second reply: ready, or a failure to prepare that ends the
+     * handoff. When the handoff into the machine has already ended, as one
+     * dispatched on arrival does at acceptance, the failure ends the handoff
+     * carrying the units out of it.
+     */
     async lateReply(a) {
-        const row = this.d.state.rowForDispatch(a.cmdId);
-        if (!row?.toMachine)
-            return;
-        const context = { row: row.id, machine: row.toMachine, cmdId: a.cmdId, reason: a.reason };
-        if (a.status === protocol_1.REPLY_STATUS.COMPLETED)
-            return this.d.log.info(log_1.GATEWAY_LOG.DISPATCH_READY, context);
+        const { state, log } = this.d;
+        const into = state.rowForDispatch(a.cmdId);
+        const m = into?.toMachine;
+        if (!into || !m)
+            return [];
+        const context = { row: into.id, machine: m, cmdId: a.cmdId, reason: a.reason };
+        if (a.status === protocol_1.REPLY_STATUS.COMPLETED) {
+            log.info(log_1.GATEWAY_LOG.DISPATCH_READY, context);
+            return [];
+        }
         if (a.status !== protocol_1.REPLY_STATUS.FAILED)
-            return;
-        this.d.log.warn(log_1.GATEWAY_LOG.DISPATCH_FAILED, context);
-        await this.apply((0, plan_shared_1.failHandoff)(this.d.state, row, row.toMachine, {
-            received: false, errorCode: contracts_1.HANDOFF_ERROR.DISPATCH_FAILED, detail: `${row.toMachine} could not prepare the job: ${a.reason}`,
+            return [];
+        const row = into.ended ? onwardRow(state, into, m) : into;
+        log.warn(log_1.GATEWAY_LOG.DISPATCH_FAILED, { ...context, ...(into.ended ? { onward: row?.id ?? null } : {}) });
+        if (!row)
+            return [];
+        return this.apply((0, plan_shared_1.failHandoff)(state, row, m, {
+            received: false, errorCode: contracts_1.HANDOFF_ERROR.DISPATCH_FAILED, detail: `${m} could not prepare the job: ${a.reason}`, ...(a.code ? { code: a.code } : {}),
         }));
     }
     /** Add the item; when the row then holds every key the action waits for, resolve it. */
@@ -110,15 +157,18 @@ class Executor {
         const { lt, state } = this.d;
         const result = await lt.accumulate(a.as, a.rowId, a.itemKey, a.payload, a.metadata);
         this.check(a, result);
+        const added = { ...outcomeOf('accumulate', a.rowId, result), itemKey: a.itemKey };
         if (!a.complete || result.outcome === escalations_1.VERB_OUTCOME.INVALID)
-            return;
+            return [added];
         const held = new Set(result.itemKeys ?? await lt.itemKeys(a.rowId));
         if (!a.complete.keys.every((k) => held.has(k)))
-            return;
+            return [added];
         if (a.complete.then)
-            return this.apply(a.complete.then);
-        this.check(a, await lt.resolve(a.as, a.rowId, a.complete.payload ?? {}));
+            return [added, ...await this.apply(a.complete.then)];
+        const resolved = await lt.resolve(a.as, a.rowId, a.complete.payload ?? {});
+        this.check(a, resolved);
         state.close(a.rowId);
+        return [added, outcomeOf('resolve', a.rowId, resolved)];
     }
     check(a, result) {
         const rowId = a.rowId;
@@ -133,17 +183,19 @@ class Executor {
         }
     }
     async createAlarmRow(a) {
+        this.live();
         const { id } = await this.d.lt.create(actions_1.CONTROLLER, { ...a.row, role: (0, line_1.operatorRole)(this.d.line) });
         this.d.log.info(log_1.GATEWAY_LOG.ALARM_ROW, { row: id, machine: a.machineId, alarm: a.alarmId });
         const track = this.d.state.alarms.get(this.d.state.alarmKey(a.machineId, a.alarmId));
         const raisedAt = a.row.metadata?.raisedAt;
         if (track && (!track.raisedAt || !raisedAt || track.raisedAt === raisedAt)) {
             track.rowId = id;
-            return;
+            return id;
         }
         // Cleared at the machine, or raised again, while the row was being created.
         const note = track ? `${a.machineId} raised ${a.alarmId} again; this one ended` : `cleared at ${a.machineId}`;
         await this.d.lt.resolve(actions_1.CONTROLLER, id, { decision: contracts_1.DECISION.CLEARED, note });
+        return id;
     }
     /** Raise a quiet row for each connected machine silent longer than `quietMs`. */
     checkQuiet(machineIds, quietMs) {
@@ -157,6 +209,7 @@ class Executor {
         }
     }
     async raiseQuiet(machineId, silentMs) {
+        this.live();
         const { id } = await this.d.lt.create(actions_1.CONTROLLER, {
             type: contracts_1.ROW_TYPE.MACHINE_QUIET, role: (0, line_1.operatorRole)(this.d.line), priority: 2,
             description: `${machineId} is connected but has sent nothing for ${Math.round(silentMs / 1000)} s`,
@@ -179,11 +232,12 @@ class Executor {
         link.watching = false;
         if (link.online || link.rowId)
             return;
+        this.live();
         const since = new Date(link.since).toISOString();
         const { id } = await this.d.lt.create(actions_1.CONTROLLER, {
             type: contracts_1.ROW_TYPE.MACHINE_OFFLINE, role: (0, line_1.operatorRole)(this.d.line), priority: 2,
             description: `${machineId} has been offline since ${since}`,
-            metadata: { siteId: this.d.line.siteId, lineId: this.d.line.lineId, machineId, offlineSince: since },
+            metadata: { siteId: this.d.line.siteId, lineId: this.d.line.lineId, machineId, offlineSince: since, ...(link.reason ? { reason: link.reason } : {}) },
         });
         this.d.log.info(log_1.GATEWAY_LOG.OFFLINE_ROW, { row: id, machine: machineId });
         if (!link.online)
@@ -193,3 +247,14 @@ class Executor {
     }
 }
 exports.Executor = Executor;
+/** The open handoff out of `m` for units a closed handoff brought into it. */
+function onwardRow(state, into, m) {
+    if (into.ended !== state_1.ROW_END.RESOLVED || into.dispatch !== state_1.DISPATCH_STATE.ACCEPTED)
+        return undefined;
+    for (const u of into.units) {
+        const row = state.openFor(u.unitId, (r) => r.fromMachine === m);
+        if (row)
+            return row;
+    }
+    return undefined;
+}

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

@@ -3,15 +3,18 @@
  * reads escalation events (a new handoff row means "dispatch"), reads every
  * machine message on the line (a receipt means "resolve"), and performs the
  * verbs a person would, as the machine. Neither side knows about the other.
+ * Every message read or sent is recorded on the wire (wire.ts).
  */
 import { type HandoffRowAdapter } from '../rows';
 import { type AddressBook } from './address-book';
 import type { LineDef } from '../../../lib/machines/line';
 import { type LineCodec } from '../../../lib/machines/protocol';
-import { type EscalationFeed, type MachineBus } from '../../../lib/machines/transport';
+import { type EscalationFeed, type InboundMessage, type MachineBus } from '../../../lib/machines/transport';
+import type { InspectResult } from '../../../types/machines-view';
 import type { LineEscalations } from './escalations';
 import { type GatewayLog } from './log';
 import { GatewayState } from './state';
+import { type WireSink } from './wire';
 export interface GatewaySettings {
     topicRoot: string;
     replyTimeoutMs: number;
@@ -23,6 +26,12 @@ export interface GatewaySettings {
     quietMs: number;
     /** How long confirmed message ids gather before a receipt goes out (codecs with receipts). */
     receiptDelayMs?: number;
+    /** Note each job's start, progress steps and pauses on the row that holds it; off unless set. */
+    lifecycle?: boolean;
+    /** With lifecycle notes, progress is noted each time it crosses this many percent; 0 notes none. */
+    progressStep?: number;
+    /** Record telemetry messages on the wire too; off unless set. */
+    wireTelemetry?: boolean;
 }
 export interface GatewayDeps {
     bus: MachineBus;
@@ -37,6 +46,8 @@ export interface GatewayDeps {
     codec?: LineCodec;
     /** Where a line that learns addresses keeps them; in memory by default. */
     addresses?: AddressBook;
+    /** Where wire records go; Long Tail's events by default. */
+    wire?: WireSink;
 }
 export declare class MachineGateway {
     private readonly deps;
@@ -48,12 +59,22 @@ export declare class MachineGateway {
     private readonly log;
     private readonly addresses;
     private readonly admission;
+    private readonly wire;
     private quietTimer?;
     constructor(deps: GatewayDeps);
     start(): Promise<void>;
+    /**
+     * Hand the line over cleanly: nothing new is raised or sent, a message
+     * still being handled is nak'd for the next leader if it would make a row,
+     * receipts for what was applied go out, then the sessions close.
+     */
     stop(): Promise<void>;
+    /** Machines that report only changes are asked for their full state once the gateway listens. */
+    private askEveryMachine;
     /** Resolves when no dispatch is in flight (tests). */
     idle(): Promise<void>;
+    /** A dry run of one message on a copy of the state: nothing is applied (inspect.ts). */
+    inspect(msg: Pick<InboundMessage, 'topic' | 'payload' | 'retained'>): InspectResult;
     /**
      * On taking the line: open handoff and command rows (a dispatch or command
      * interrupted by a restart is sent again with the same cmdId), the gateway's

package/build/services/machines/gateway/gateway.js

@@ -4,6 +4,7 @@
  * reads escalation events (a new handoff row means "dispatch"), reads every
  * machine message on the line (a receipt means "resolve"), and performs the
  * verbs a person would, as the machine. Neither side knows about the other.
+ * Every message read or sent is recorded on the wire (wire.ts).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineGateway = void 0;
@@ -15,14 +16,18 @@ const address_book_1 = require("./address-book");
 const admission_1 = require("./admission");
 const protocol_1 = require("../../../lib/machines/protocol");
 const transport_1 = require("../../../lib/machines/transport");
+const publish_1 = require("../../../lib/events/publish");
 const reply_waiter_1 = require("./reply-waiter");
 const executor_1 = require("./executor");
+const dispatcher_1 = require("./dispatcher");
+const inspect_1 = require("./inspect");
 const log_1 = require("./log");
 const plan_escalation_1 = require("./plan-escalation");
 const pacing_1 = require("./pacing");
 const plan_machine_1 = require("./plan-machine");
 const state_1 = require("./state");
 const receipts_1 = require("./receipts");
+const wire_1 = require("./wire");
 class MachineGateway {
     constructor(deps) {
         this.deps = deps;
@@ -32,22 +37,30 @@ class MachineGateway {
         this.codec = deps.codec ?? (0, protocol_1.genericCodec)({ root: deps.settings.topicRoot, line: deps.line });
         this.state.unitsPerDispatch = this.codec.unitsPerDispatch;
         this.state.dispatchOnArrival = this.codec.dispatchOn === protocol_1.DISPATCH_ON.ARRIVAL;
+        this.state.rowOps = (0, protocol_1.declaredRowOps)(this.codec);
+        this.state.lifecycle = deps.settings.lifecycle === true;
+        this.state.retainedAlarms = this.codec.retainedAlarms === true;
+        this.state.progressStep = deps.settings.progressStep ?? this.state.progressStep;
         this.addresses = deps.addresses ?? new address_book_1.MemoryAddressBook();
+        this.wire = new wire_1.WireRecorder(deps.line, deps.wire ?? publish_1.publishMachineWireEvent, { telemetry: deps.settings.wireTelemetry === true });
         this.executor = new executor_1.Executor({
-            addresses: this.addresses,
+            addresses: this.addresses, wire: this.wire,
             bus: deps.bus, lt: deps.lt, replies: new reply_waiter_1.ReplyWaiter(), state: this.state, line: deps.line,
             codec: this.codec, replyTimeoutMs: deps.settings.replyTimeoutMs,
             dispatchAttempts: deps.settings.dispatchAttempts, offlineDebounceMs: deps.settings.offlineDebounceMs, log: this.log,
         });
         this.admission = { state: this.state, line: deps.line, executor: this.executor, log: this.log, pace: () => this.pace() };
-        this.receipts = new receipts_1.ReceiptBatcher({ bus: deps.bus, codec: this.codec, delayMs: deps.settings.receiptDelayMs ?? DEFAULT_RECEIPT_DELAY_MS, log: this.log });
+        this.receipts = new receipts_1.ReceiptBatcher({ bus: deps.bus, codec: this.codec, delayMs: deps.settings.receiptDelayMs ?? DEFAULT_RECEIPT_DELAY_MS, log: this.log, wire: this.wire });
     }
     async start() {
         await this.deps.bus.connect();
         await this.deps.feed.connect();
+        this.state.takenAt = Date.now();
         await this.reconcile();
         await this.deps.feed.consume((event) => this.onEscalation(event));
         await this.deps.bus.consume((msg) => this.onMachine(msg));
+        if (this.codec.snapshotOnStart)
+            await this.askEveryMachine();
         const { quietMs } = this.deps.settings;
         if (quietMs > 0) {
             const machines = this.deps.line.machines.map((m) => m.machineId);
@@ -55,18 +68,37 @@ class MachineGateway {
         }
         this.log.info(log_1.GATEWAY_LOG.STARTED, { site: this.deps.line.siteId, line: this.deps.line.lineId });
     }
+    /**
+     * Hand the line over cleanly: nothing new is raised or sent, a message
+     * still being handled is nak'd for the next leader if it would make a row,
+     * receipts for what was applied go out, then the sessions close.
+     */
     async stop() {
         if (this.quietTimer)
             clearInterval(this.quietTimer);
         this.executor.stop();
+        await this.deps.feed.unsubscribe();
+        await this.deps.bus.unsubscribe();
+        await this.executor.idle();
         await this.receipts.flush();
         await this.deps.feed.close();
         await this.deps.bus.close();
     }
+    /** Machines that report only changes are asked for their full state once the gateway listens. */
+    async askEveryMachine() {
+        const at = Date.now();
+        await this.executor.apply(this.deps.line.machines.map((m) => ({
+            kind: 'command', machineId: m.machineId, op: protocol_1.OP.SNAPSHOT, cmdId: `${m.machineId}:takeover:${at}`, args: {},
+        })));
+    }
     /** Resolves when no dispatch is in flight (tests). */
     idle() {
         return this.executor.idle();
     }
+    /** A dry run of one message on a copy of the state: nothing is applied (inspect.ts). */
+    inspect(msg) {
+        return (0, inspect_1.dryRun)({ state: this.state, line: this.deps.line, codec: this.codec, dispatchTtlMs: this.deps.settings.dispatchTtlMs }, { ...msg, deliveries: 1 });
+    }
     /**
      * On taking the line: open handoff and command rows (a dispatch or command
      * interrupted by a restart is sent again with the same cmdId), the gateway's
@@ -80,6 +112,7 @@ class MachineGateway {
             const addresses = await (0, reconcile_1.restoreAddresses)(this.state, this.addresses, this.deps.line);
             const handoffs = await this.reconcileHandoffs();
             await this.executor.apply(await (0, reconcile_1.arrivalsOnRows)(this.state, this.deps.lt, this.deps.settings.dispatchTtlMs));
+            await (0, reconcile_1.notesOnRows)(this.state, this.deps.lt);
             const commands = await this.reconcileCommands();
             const restored = await (0, reconcile_1.restoreLineRows)(this.state, this.deps.lt, this.deps.line);
             await this.resync();
@@ -121,18 +154,31 @@ class MachineGateway {
     async resync() {
         const { line } = this.deps;
         const active = new Set();
-        for (const msg of await this.deps.bus.retained((0, protocol_1.lineFilter)(this.codec.root, line.siteId, line.lineId))) {
-            for (const raw of this.decode(msg.topic, msg.payload, true)) {
-                if (!raw.parsed)
-                    continue;
-                const seen = await (0, admission_1.admitSender)(this.admission, msg.topic, raw);
-                if (!('parsed' in seen) || !seen.parsed)
-                    continue;
-                if (seen.parsed.kind === protocol_1.MESSAGE_KIND.ALARM && seen.body?.body?.active)
-                    active.add(this.state.alarmKey(seen.parsed.ident.machineId, seen.parsed.key));
-                await this.applyMachine(msg.topic, seen.parsed, seen.body);
+        this.state.readingRetained = true;
+        try {
+            for (const read of await this.deps.bus.retained((0, protocol_1.lineFilter)(this.codec.root, line.siteId, line.lineId))) {
+                const msg = { ...read, retained: true };
+                for (const raw of this.decode(msg)) {
+                    if (!raw.parsed)
+                        continue;
+                    const admitted = await (0, admission_1.admitSender)(this.admission, msg.topic, raw);
+                    if (!('seen' in admitted)) {
+                        this.wire.inbound(msg, raw, admitted, 1, admitted.sender);
+                        continue;
+                    }
+                    const { seen } = admitted;
+                    if (seen.parsed.kind === protocol_1.MESSAGE_KIND.ALARM && seen.body?.body?.active)
+                        active.add(this.state.alarmKey(seen.parsed.ident.machineId, seen.parsed.key));
+                    const applied = await this.applyMachine(msg.topic, seen.parsed, seen.body);
+                    this.wire.inbound(msg, seen, { ...applied, actions: [...admitted.actions, ...applied.actions] }, 1);
+                }
             }
         }
+        finally {
+            this.state.readingRetained = false;
+        }
+        if (!this.state.retainedAlarms)
+            return;
         for (const gone of (0, reconcile_1.alarmsClearedMeanwhile)(this.state, active)) {
             this.state.alarms.delete(gone.key);
             await this.executor.apply([{ kind: 'resolve', as: actions_1.CONTROLLER, rowId: gone.rowId, payload: { decision: contracts_1.DECISION.CLEARED, note: `cleared at ${gone.machineId} while the gateway was away` } }]);
@@ -147,7 +193,8 @@ class MachineGateway {
             return transport_1.DISPOSITION.ACK;
         }
         catch (err) {
-            this.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { event: event.type, error: err.message });
+            if (!(err instanceof dispatcher_1.GatewayStopped))
+                this.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { event: event.type, error: err.message });
             return transport_1.DISPOSITION.NAK;
         }
     }
@@ -165,19 +212,21 @@ class MachineGateway {
         return { ...event, role: row.role, data: row };
     }
     async onMachine(msg) {
-        const decoded = this.decode(msg.topic, msg.payload, msg.retained);
+        const decoded = this.decode(msg);
         const acted = [];
         let outcome = transport_1.DISPOSITION.TERM;
         let failed = false;
         for (const raw of decoded) {
             if (!raw.parsed)
                 continue;
-            const seen = await (0, admission_1.admitSender)(this.admission, msg.topic, raw);
-            if (!('parsed' in seen)) {
-                failed ||= seen.failed;
-                outcome = worse(outcome, seen.disposition);
+            const admitted = await (0, admission_1.admitSender)(this.admission, msg.topic, raw);
+            if (!('seen' in admitted)) {
+                failed ||= admitted.failed;
+                outcome = worse(outcome, admitted.disposition);
+                this.wire.inbound(msg, raw, admitted, msg.deliveries, admitted.sender);
                 continue;
             }
+            const { seen } = admitted;
             acted.push(seen);
             if (seen.violations.length && msg.deliveries === 1) {
                 this.log.warn(log_1.GATEWAY_LOG.CONTRACT_VIOLATION, { topic: msg.topic, violations: seen.violations });
@@ -187,9 +236,10 @@ class MachineGateway {
                 : await this.applyMachine(msg.topic, seen.parsed, seen.body);
             failed ||= applied.failed;
             outcome = worse(outcome, applied.disposition);
+            this.wire.inbound(msg, seen, { ...applied, actions: [...admitted.actions, ...applied.actions] }, msg.deliveries);
         }
         // No row has claimed it after this many tries, so it is not racing its row: stop. A failed verb always retries.
-        if (outcome === transport_1.DISPOSITION.NAK && !failed && msg.deliveries >= MAX_DELIVERIES) {
+        if (outcome === transport_1.DISPOSITION.NAK && !failed && msg.deliveries >= wire_1.MAX_DELIVERIES) {
             this.log.warn(log_1.GATEWAY_LOG.UNMATCHED, { topic: msg.topic, deliveries: msg.deliveries });
             outcome = transport_1.DISPOSITION.TERM;
         }
@@ -198,14 +248,19 @@ class MachineGateway {
         return outcome;
     }
     /** A message the codec cannot read is not retried: it is logged and has no effect. */
-    decode(topic, payload, retained) {
+    decode(msg) {
+        let decoded;
         try {
-            return this.codec.decode(topic, payload, retained);
+            decoded = this.codec.decode(msg.topic, msg.payload, msg.retained);
         }
         catch (err) {
-            this.log.warn(log_1.GATEWAY_LOG.UNREADABLE, { topic, error: err.message });
+            this.log.warn(log_1.GATEWAY_LOG.UNREADABLE, { topic: msg.topic, error: err.message });
+            this.wire.unreadable(msg, err.message);
             return [];
         }
+        if (!decoded.length)
+            this.wire.unreadable(msg, 'not a machine message', 'none');
+        return decoded;
     }
     /** Done with the message: confirm each id its codec asked to confirm. */
     confirm(decoded) {
@@ -224,21 +279,21 @@ class MachineGateway {
         }
         catch (err) {
             this.log.warn(log_1.GATEWAY_LOG.UNREADABLE, { topic, error: err.message });
-            return { disposition: transport_1.DISPOSITION.TERM, failed: false };
+            return { disposition: transport_1.DISPOSITION.TERM, failed: false, actions: [{ verb: 'unreadable', detail: err.message }] };
         }
         try {
-            await this.executor.apply(plan.actions);
+            const actions = await this.executor.apply(plan.actions);
             await this.pace();
-            return { disposition: plan.disposition, failed: false };
+            return { disposition: plan.disposition, failed: false, actions };
         }
         catch (err) {
-            this.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic, error: err.message });
-            return { disposition: transport_1.DISPOSITION.NAK, failed: true };
+            if (!(err instanceof dispatcher_1.GatewayStopped))
+                this.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic, error: err.message });
+            return { disposition: transport_1.DISPOSITION.NAK, failed: true, actions: [] };
         }
     }
 }
 exports.MachineGateway = MachineGateway;
-const MAX_DELIVERIES = 30;
 const DEFAULT_RECEIPT_DELAY_MS = 250;
 const RANK = { [transport_1.DISPOSITION.TERM]: 0, [transport_1.DISPOSITION.ACK]: 1, [transport_1.DISPOSITION.NAK]: 2 };
 /** One wire message may decode to several; any that must be retried retries the message. */

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

@@ -8,3 +8,6 @@ export * from './provision';
 export * from './state';
 export * from './address-book';
 export * from './registration';
+export * from './wire';
+export * from './project';
+export * from './inspect';

package/build/services/machines/gateway/index.js

@@ -24,3 +24,6 @@ __exportStar(require("./provision"), exports);
 __exportStar(require("./state"), exports);
 __exportStar(require("./address-book"), exports);
 __exportStar(require("./registration"), exports);
+__exportStar(require("./wire"), exports);
+__exportStar(require("./project"), exports);
+__exportStar(require("./inspect"), exports);

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

@@ -0,0 +1,17 @@
+/**
+ * A dry run of one wire message: what the codec reads and what the gateway
+ * would do, planned on a copy of the state so the line is untouched and no
+ * row is created or changed.
+ */
+import type { LineDef } from '../../../lib/machines/line';
+import type { LineCodec } from '../../../lib/machines/protocol';
+import type { InboundMessage } from '../../../lib/machines/transport';
+import type { InspectResult } from '../../../types/machines-view';
+import type { GatewayState } from './state';
+export interface DryRunContext {
+    state: GatewayState;
+    line: LineDef;
+    codec: LineCodec;
+    dispatchTtlMs: number;
+}
+export declare function dryRun(ctx: DryRunContext, msg: InboundMessage): InspectResult;