@hotmeshio/long-tail 0.27.0 → 0.28.0

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,18 +37,20 @@ 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();
@@ -61,10 +68,17 @@ 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();
@@ -81,6 +95,10 @@ class MachineGateway {
     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
@@ -138,16 +156,21 @@ class MachineGateway {
         const active = new Set();
         this.state.readingRetained = true;
         try {
-            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)) {
+            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 seen = await (0, admission_1.admitSender)(this.admission, msg.topic, raw);
-                    if (!('parsed' in seen) || !seen.parsed)
+                    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));
-                    await this.applyMachine(msg.topic, seen.parsed, seen.body);
+                    const applied = await this.applyMachine(msg.topic, seen.parsed, seen.body);
+                    this.wire.inbound(msg, seen, { ...applied, actions: [...admitted.actions, ...applied.actions] }, 1);
                 }
             }
         }
@@ -170,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;
         }
     }
@@ -188,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 });
@@ -210,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;
         }
@@ -221,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) {
@@ -247,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;

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

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dryRun = dryRun;
+const plan_machine_1 = require("./plan-machine");
+const registration_1 = require("./registration");
+const wire_1 = require("./wire");
+/** What admitting the sender would do, or null when the message would be acted on. */
+function admission(state, line, raw) {
+    const sender = (0, registration_1.resolveSender)(state, line, raw);
+    if (sender.status === registration_1.SENDER.BOUND)
+        return { seen: sender.seen, actions: [{ verb: 'ack', detail: `bind ${sender.machineId} to ${sender.address}` }] };
+    if (sender.seen)
+        return { seen: sender.seen, actions: [] };
+    if (sender.status === registration_1.SENDER.UNKNOWN)
+        return { seen: null, actions: [{ verb: 'none', detail: `${sender.address} claims no station on this line` }] };
+    const raised = state.claimRaised(sender.address, sender.machineId);
+    return {
+        seen: null,
+        actions: [raised
+                ? { verb: 'none', detail: `${sender.address} says it is ${sender.machineId}; waiting for a person` }
+                : { verb: 'create-row', detail: `${sender.address} says it is ${sender.machineId}; a person decides` }],
+    };
+}
+function planOne(ctx, state, raw) {
+    const admitted = admission(state, ctx.line, raw);
+    if (!admitted.seen)
+        return admitted.actions;
+    if (raw.violations.length && ctx.codec.strict)
+        return [...admitted.actions, { verb: 'hold', detail: raw.violations.join('; ') }];
+    try {
+        const plan = (0, plan_machine_1.planMachineMessage)(state, admitted.seen.parsed, admitted.seen.body, ctx.dispatchTtlMs);
+        const actions = [...admitted.actions, ...plan.actions.map(wire_1.plannedAction)];
+        return (0, wire_1.appliedActions)({ disposition: plan.disposition, failed: false, actions }, 1);
+    }
+    catch (err) {
+        return [...admitted.actions, { verb: 'unreadable', detail: err.message }];
+    }
+}
+function dryRun(ctx, msg) {
+    let decoded;
+    try {
+        decoded = ctx.codec.decode(msg.topic, msg.payload, msg.retained);
+    }
+    catch (err) {
+        return { kind: null, event: null, summary: err.message, inspections: [], violations: [], actions: [{ verb: 'unreadable', detail: err.message }] };
+    }
+    if (!decoded.length) {
+        return { kind: null, event: null, summary: 'not a machine message', inspections: [], violations: [], actions: [{ verb: 'none', detail: 'not a machine message' }] };
+    }
+    const state = ctx.state.clone();
+    const actions = [];
+    const violations = [];
+    for (const raw of decoded) {
+        violations.push(...raw.violations);
+        if (raw.parsed)
+            actions.push(...planOne(ctx, state, raw));
+    }
+    const [first] = decoded;
+    return {
+        kind: first.parsed?.kind ?? null, event: (0, wire_1.eventOf)(first), summary: (0, wire_1.summarize)(first),
+        inspections: decoded, violations, actions: actions.length ? actions : [{ verb: 'unreadable', detail: 'unknown topic' }],
+    };
+}

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

@@ -1,3 +1,4 @@
+import { publishMachineLogEvent } from '../../../lib/events/publish';
 export declare const GATEWAY_LOG: {
     readonly STARTED: "machine_gateway.started";
     readonly RECONCILED: "machine_gateway.reconciled";
@@ -39,3 +40,10 @@ export interface GatewayLog {
 }
 export declare const consoleLog: GatewayLog;
 export declare const silentLog: GatewayLog;
+/** Each entry published as `machine.log.<site>.<line>.<event>` with its context, for the line's dashboard view. */
+export declare function eventsLog(line: {
+    siteId: string;
+    lineId: string;
+}, publish?: typeof publishMachineLogEvent): GatewayLog;
+/** Every entry goes to each log in turn. */
+export declare function composeLogs(...logs: GatewayLog[]): GatewayLog;

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

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.silentLog = exports.consoleLog = exports.GATEWAY_LOG = void 0;
+exports.eventsLog = eventsLog;
+exports.composeLogs = composeLogs;
+const publish_1 = require("../../../lib/events/publish");
 exports.GATEWAY_LOG = {
     STARTED: 'machine_gateway.started',
     RECONCILED: 'machine_gateway.reconciled',
@@ -40,3 +43,18 @@ exports.consoleLog = {
     error: (event, context) => console.error(JSON.stringify({ level: 'error', event, ...context })),
 };
 exports.silentLog = { info: () => undefined, warn: () => undefined, error: () => undefined };
+/** Each entry published as `machine.log.<site>.<line>.<event>` with its context, for the line's dashboard view. */
+function eventsLog(line, publish = publish_1.publishMachineLogEvent) {
+    const emit = (level) => (event, context) => {
+        publish({ siteId: line.siteId, lineId: line.lineId, level, event, context }).catch(() => undefined);
+    };
+    return { info: emit('info'), warn: emit('warn'), error: emit('error') };
+}
+/** Every entry goes to each log in turn. */
+function composeLogs(...logs) {
+    const each = (level) => (event, context) => {
+        for (const log of logs)
+            log[level](event, context);
+    };
+    return { info: each('info'), warn: each('warn'), error: each('error') };
+}

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

@@ -39,6 +39,7 @@ function dispatchArgs(row, expiresAt) {
         expiresAt: (0, protocol_1.isoTs)(expiresAt),
         ...(row.artifactUrl ? { artifact: { url: row.artifactUrl, sha256: row.artifactSha256 } } : {}),
         ...(row.parameters ? { parameters: row.parameters } : {}),
+        ...(row.refs ? { refs: row.refs } : {}),
     };
 }
 /**

package/build/services/machines/gateway/plan-escalation.js

@@ -93,8 +93,9 @@ function commandRefusal(state, line, c, role) {
     const own = (0, line_1.machineRole)((0, line_1.machineById)(line, c.machineId));
     if (role !== own)
         return `commands for ${c.machineId} are parked on ${own}, not ${role}`;
-    if (!protocol_1.CONTROL_OPS.includes(c.op))
-        return `${c.op} is not a command a row may ask for; one of ${protocol_1.CONTROL_OPS.join(', ')}`;
+    const allowed = rowOps(state);
+    if (!allowed.includes(c.op))
+        return `${c.op} is not a command a row may ask for; one of ${allowed.join(', ')}`;
     if (c.op === protocol_1.OP.CANCEL && typeof c.args.jobId !== 'string')
         return `${protocol_1.OP.CANCEL} needs args.jobId, the job to withdraw or stop`;
     if (!(0, registration_1.reachable)(state, line, c.machineId))
@@ -110,7 +111,7 @@ function planCommandRow(state, line, event) {
     if (event.verb !== VERB.CREATED && event.verb !== VERB.CLAIMED)
         return [];
     const c = (0, commands_1.readCommandFacets)(event.data?.metadata);
-    if (!c || !state.trackCommand(id))
+    if (!c || !state.trackCommand(id, c.machineId))
         return [];
     const refusal = commandRefusal(state, line, c, event.role);
     if (refusal) {
@@ -119,6 +120,10 @@ function planCommandRow(state, line, event) {
     const createdAt = event.data?.created_at ? new Date(event.data.created_at).getTime() : NaN;
     return [{ kind: 'control', rowId: id, machineId: c.machineId, op: c.op, args: c.args, ...(Number.isFinite(createdAt) ? { createdAt } : {}) }];
 }
+/** The ops a machine-command row may ask for: the control ops, a snapshot, and the codec's own. */
+function rowOps(state) {
+    return [...protocol_1.CONTROL_OPS, protocol_1.OP.SNAPSHOT, ...state.rowOps];
+}
 function onLine(line, machineId) {
     return !!machineId && line.machines.some((m) => m.machineId === machineId);
 }

package/build/services/machines/gateway/plan-machine.js

@@ -36,7 +36,7 @@ function planMachineMessage(state, parsed, env, dispatchTtlMs) {
 function planByKind(state, m, parsed, env, b, ttl) {
     switch (parsed.kind) {
         case protocol_1.MESSAGE_KIND.REPLY:
-            return ack([{ kind: 'settleReply', cmdId: b.cmdId, status: b.status, reason: b.reason }]);
+            return ack([{ kind: 'settleReply', cmdId: b.cmdId, status: b.status, reason: b.reason, ...(typeof b.code === 'string' ? { code: b.code } : {}) }]);
         case protocol_1.MESSAGE_KIND.JOB:
             return planJob(state, m, b, env?.at, ttl);
         case protocol_1.MESSAGE_KIND.ALARM:
@@ -139,7 +139,8 @@ function planJob(state, m, b, at, ttl) {
         if (b.result === protocol_1.JOB_RESULT.OK)
             return ack([released]);
         return ack([released, ...(0, plan_shared_1.failHandoff)(state, row, m, {
-                received: false, unitId, errorCode: contracts_1.HANDOFF_ERROR.SENDER_REJECTED, reason: b.reason ?? null, detail: `${m} finished ${unitId}: ${b.result}${b.reason ? ` (${b.reason})` : ''}`,
+                received: false, unitId, errorCode: contracts_1.HANDOFF_ERROR.SENDER_REJECTED, result: b.result, reason: b.reason ?? null,
+                detail: `${m} finished ${unitId}: ${b.result}${b.reason ? ` (${b.reason})` : ''}`,
             })]);
     }
     if (b.event === protocol_1.JOB_EVENT.TRANSFER_FAILED) {
@@ -198,7 +199,7 @@ function planAlarm(state, parsed, alarmId, env) {
     const superseded = known?.rowId && known.open
         ? [{ kind: 'resolve', as: actions_1.CONTROLLER, rowId: known.rowId, payload: { decision: contracts_1.DECISION.CLEARED, note: `${m} raised ${alarmId} again; this one ended` } }]
         : [];
-    const track = { machineId: m, alarmId, raisedAt: b.raisedAt, open: true };
+    const track = { machineId: m, alarmId, raisedAt: b.raisedAt, level: b.level, open: true };
     state.alarms.set(key, track);
     return ack([...superseded, ...(0, lifecycle_1.notePause)(state, track, b), {
             kind: 'createAlarmRow', machineId: m, alarmId,
@@ -222,10 +223,12 @@ function catalogEnvelope(catalog) {
 }
 function planPresence(state, m, b) {
     const link = state.link(m);
+    const session = typeof b.sessionId === 'string' ? b.sessionId : undefined;
     if (b.online !== true) {
         if (link.online)
             link.since = Date.now();
         link.online = false;
+        link.reason = typeof b.reason === 'string' ? b.reason : undefined;
         if (link.rowId || link.watching)
             return ack();
         link.watching = true;
@@ -234,12 +237,17 @@ function planPresence(state, m, b) {
     if (b.software)
         link.software = b.software;
     const wasOffline = !link.online;
+    // A new session while online: the machine reconnected before its offline presence was heard.
+    const reconnected = !!session && !!link.sessionId && session !== link.sessionId;
     link.online = true;
     link.watching = false;
+    link.reason = undefined;
+    if (session)
+        link.sessionId = session;
     const actions = [];
     // Back from a drop: ask for the full state rather than wait for the next heartbeat.
-    if (wasOffline)
-        actions.push({ kind: 'command', machineId: m, op: protocol_1.OP.SNAPSHOT, cmdId: `${m}:resync:${link.since}`, args: {} });
+    if (wasOffline || reconnected)
+        actions.push({ kind: 'command', machineId: m, op: protocol_1.OP.SNAPSHOT, cmdId: `${m}:resync:${session ?? link.since}`, args: {} });
     if (link.rowId) {
         actions.push({ kind: 'resolve', as: actions_1.CONTROLLER, rowId: link.rowId, payload: { decision: contracts_1.DECISION.RESTORED, note: `${m} back online` } });
         link.rowId = undefined;
@@ -252,8 +260,10 @@ function planSnapshot(state, m, b, ttl) {
     if (b.software)
         link.software = b.software;
     const jobIds = Array.isArray(b.jobs) ? b.jobs.map((j) => j?.jobId).filter((id) => typeof id === 'string') : [];
-    if (Array.isArray(b.jobs))
+    if (Array.isArray(b.jobs)) {
         state.keepHeld(m, new Set(jobIds));
+        link.jobs = b.jobs;
+    }
     const fresh = !state.retainedAlarms && !state.readingRetained && Array.isArray(b.alarms);
     const cleared = fresh ? alarmsNoLongerListed(state, m, b.alarms) : [];
     const answer = { kind: 'settleSnapshot', machineId: m, jobIds };

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

@@ -0,0 +1,9 @@
+/**
+ * The line as its leader sees it, for the dashboard: each machine's link,
+ * held units, open rows and alarms from the gateway state, and the claims
+ * waiting for a person. Pure: reads the state and the line, changes nothing.
+ */
+import { type LineDef } from '../../../lib/machines/line';
+import type { LineView } from '../../../types/machines-view';
+import type { GatewayState } from './state';
+export declare function projectLine(state: GatewayState, line: LineDef): LineView;

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

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * The line as its leader sees it, for the dashboard: each machine's link,
+ * held units, open rows and alarms from the gateway state, and the claims
+ * waiting for a person. Pure: reads the state and the line, changes nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectLine = projectLine;
+const line_1 = require("../../../lib/machines/line");
+const protocol_1 = require("../../../lib/machines/protocol");
+const at = (ms) => (ms ? (0, protocol_1.isoTs)(ms) : null);
+function addressOf(state, line, def) {
+    if ((0, line_1.learnsAddress)(line, def.machineId))
+        return state.learnedAddress(def.machineId) ?? null;
+    return def.address ?? def.machineId;
+}
+function alarmsOf(state, machineId) {
+    return [...state.alarms.values()]
+        .filter((track) => track.machineId === machineId)
+        .map((track) => ({ alarmId: track.alarmId, level: track.level ?? '', raisedAt: track.raisedAt ?? '', rowId: track.rowId ?? null }));
+}
+/** The handoff that brought a unit into a machine: open first, then the recently closed one. */
+function rowCarrying(state, machineId, unitId) {
+    const into = (r) => r.toMachine === machineId;
+    return state.openFor(unitId, into) ?? state.closedFor(unitId, into);
+}
+function machineView(state, line, def) {
+    const m = def.machineId;
+    const link = state.links.get(m);
+    const open = state.open();
+    return {
+        machineId: m, process: def.process, role: (0, line_1.machineRole)(def), address: addressOf(state, line, def),
+        online: link ? link.online : null, since: at(link?.since), lastSeen: at(link?.lastSeen),
+        software: link?.software ?? null, bootId: link?.bootId ?? null, sessionId: link?.sessionId ?? null,
+        heldUnits: state.heldUnitsAt(m).map(({ unitId }) => {
+            const row = rowCarrying(state, m, unitId);
+            return { unitId, carrierId: row?.units.find((u) => u.unitId === unitId)?.carrierId ?? null, rowId: row?.id ?? '' };
+        }),
+        rows: {
+            handoff: open.filter((r) => r.toMachine === m).length,
+            command: state.openCommandsFor(m),
+            alarm: [...state.alarms.values()].filter((t) => t.machineId === m && t.open && !!t.rowId).length,
+            offlineRowId: link?.rowId ?? null, quietRowId: link?.quietRowId ?? null,
+        },
+        alarms: alarmsOf(state, m),
+        jobs: link?.jobs ?? [],
+    };
+}
+function projectLine(state, line) {
+    return {
+        siteId: line.siteId, lineId: line.lineId, leading: true, takenAt: at(state.takenAt),
+        machines: line.machines.map((def) => machineView(state, line, def)),
+        contested: state.contested(),
+    };
+}

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

@@ -9,6 +9,7 @@
 import { type LineCodec, type MachineIdent } from '../../../lib/machines/protocol';
 import type { MachineBus } from '../../../lib/machines/transport';
 import { type GatewayLog } from './log';
+import type { WireRecorder } from './wire';
 /** Most message ids one receipt carries. */
 export declare const MAX_RECEIPT_IDS = 100;
 export interface ReceiptDeps {
@@ -17,6 +18,8 @@ export interface ReceiptDeps {
     /** How long ids gather before a receipt goes out. */
     delayMs: number;
     log: GatewayLog;
+    /** Records each receipt the gateway sends, for the line's wire view. */
+    wire?: Pick<WireRecorder, 'receipt'>;
 }
 export declare class ReceiptBatcher {
     private readonly d;

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

@@ -58,8 +58,10 @@ class ReceiptBatcher {
         this.sending.add(work);
     }
     async publish(ident, ids) {
-        for (const wire of this.d.codec.receipt(ident, ids))
+        for (const wire of this.d.codec.receipt(ident, ids)) {
             await this.d.bus.publish(wire.topic, wire.payload);
+            this.d.wire?.receipt(ident, ids, wire);
+        }
     }
 }
 exports.ReceiptBatcher = ReceiptBatcher;

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

@@ -22,8 +22,8 @@ async function restoreLineRows(state, lt, line) {
     const [alarms, offline, quiet, registrations] = await Promise.all([contracts_1.ROW_TYPE.ALARM, contracts_1.ROW_TYPE.MACHINE_OFFLINE, contracts_1.ROW_TYPE.MACHINE_QUIET, contracts_1.ROW_TYPE.MACHINE_REGISTRATION]
         .map(async (type) => (await lt.listOpen({ type, role })).filter(mine)));
     for (const row of alarms) {
-        const { machineId, alarmId, raisedAt } = row.metadata;
-        state.alarms.set(state.alarmKey(machineId, alarmId), { machineId, alarmId, raisedAt, rowId: row.id, open: true });
+        const { machineId, alarmId, raisedAt, level } = row.metadata;
+        state.alarms.set(state.alarmKey(machineId, alarmId), { machineId, alarmId, raisedAt, level, rowId: row.id, open: true });
     }
     for (const row of offline) {
         const link = state.link(row.metadata.machineId);
@@ -33,7 +33,7 @@ async function restoreLineRows(state, lt, line) {
     for (const row of quiet)
         state.link(row.metadata.machineId).quietRowId = row.id;
     for (const row of registrations)
-        state.raiseClaim(row.metadata.address, row.metadata.machineId);
+        state.raiseClaim(row.metadata.address, row.metadata.machineId, row.id);
     return { alarms: alarms.length, offline: offline.length, quiet: quiet.length, registrations: registrations.length };
 }
 /** The addresses the line learned before, for the stations that still learn theirs. */

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

@@ -106,7 +106,7 @@ function planRegistrationRow(state, line, event) {
     if (typeof md.machineId !== 'string' || typeof md.address !== 'string')
         return [];
     if (event.verb === 'created') {
-        state.raiseClaim(md.address, md.machineId);
+        state.raiseClaim(md.address, md.machineId, event.escalationId);
         return [];
     }
     state.settleClaim(md.address, md.machineId);

package/build/services/machines/gateway/reply-waiter.d.ts

@@ -1,12 +1,15 @@
 /**
  * Command replies by cmdId, and machine snapshots by machine. A wait registers
  * before the command is published and resolves with the reply, or null at the
- * deadline.
+ * deadline. Several waits on one key are all settled by the next answer, so
+ * two dispatches asking one machine what it holds share its next snapshot.
  */
 export interface CommandReply {
     cmdId: string;
     status: string;
     reason: string;
+    /** The machine's structured code for the outcome, when its reply carried one. */
+    code?: string;
 }
 /** The jobs a machine reports holding, queued or in work. */
 export type HeldJobs = Set<string>;
@@ -16,9 +19,9 @@ export declare class ReplyWaiter {
     wait(cmdId: string, timeoutMs: number): Promise<CommandReply | null>;
     /** True when a waiter took the reply. */
     settle(reply: CommandReply): boolean;
-    /** The next snapshot from `machineId`, or null at the deadline. */
+    /** The next snapshot from `machineId`, or null at the deadline; every wait in flight for the machine gets it. */
     waitSnapshot(machineId: string, timeoutMs: number): Promise<HeldJobs | null>;
-    /** Answer a status query in flight; null when there is nothing to wait for. */
+    /** Answer the status queries in flight; null when there is nothing to wait for. */
     settleSnapshot(machineId: string, jobs: HeldJobs | null): void;
     cancelAll(): void;
 }