@hotmeshio/long-tail 0.25.4 → 0.26.0

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

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Executor = void 0;
+const contracts_1 = require("../contracts");
+const line_1 = require("../../../lib/machines/line");
+const protocol_1 = require("../../../lib/machines/protocol");
+const actions_1 = require("./actions");
+const escalations_1 = require("./escalations");
+const log_1 = require("./log");
+const dispatcher_1 = require("./dispatcher");
+const plan_shared_1 = require("./plan-shared");
+const NOT_FOUND = 404;
+const CONFLICT = 409;
+class Executor {
+    constructor(d) {
+        this.d = d;
+        this.inflight = new Set();
+        this.quietPending = new Set();
+        this.timers = new Set();
+        this.dispatcher = new dispatcher_1.Dispatcher(d);
+    }
+    /** Dispatches and commands run detached so one slow reply never holds up the feed. */
+    async apply(actions) {
+        for (const action of actions) {
+            if (action.kind === 'dispatch')
+                this.track(this.dispatcher.dispatch(action));
+            else if (action.kind === 'command')
+                this.track(this.dispatcher.command(action));
+            else if (action.kind === 'control')
+                this.track(this.dispatcher.control(action));
+            else
+                await this.run(action);
+        }
+    }
+    /** Resolves when every detached dispatch has finished. */
+    async idle() {
+        while (this.inflight.size)
+            await Promise.all([...this.inflight]);
+    }
+    stop() {
+        for (const t of this.timers)
+            clearTimeout(t);
+        this.timers.clear();
+        this.d.replies.cancelAll();
+    }
+    track(work) {
+        const tracked = work.catch((err) => 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 'accumulate':
+                return this.accumulate(a);
+            case 'resolve':
+                this.check(a, await lt.resolve(a.as, a.rowId, a.payload));
+                state.close(a.rowId);
+                return;
+            case 'createAlarmRow':
+                return this.createAlarmRow(a);
+            case 'createRow': {
+                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;
+            }
+            case 'watchOffline':
+                return this.watchOffline(a.machineId);
+            case 'settleReply':
+                if (!replies.settle({ cmdId: a.cmdId, status: a.status, reason: a.reason }))
+                    await this.lateReply(a);
+                return;
+            case 'settleSnapshot':
+                replies.settleSnapshot(a.machineId, new Set(a.jobIds));
+                return;
+            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;
+            case 'refuseBinding':
+                this.d.log.warn(log_1.GATEWAY_LOG.ADDRESS_REFUSED, { machine: a.machineId, address: a.address, reason: a.reason });
+        }
+    }
+    /** A dispatch's second reply: ready, or a failure to prepare that ends the handoff. */
+    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);
+        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}`,
+        }));
+    }
+    /** Add the item; when the row then holds every key the action waits for, resolve it. */
+    async accumulate(a) {
+        const { lt, state } = this.d;
+        const result = await lt.accumulate(a.as, a.rowId, a.itemKey, a.payload, a.metadata);
+        this.check(a, result);
+        if (!a.complete || result.outcome === escalations_1.VERB_OUTCOME.INVALID)
+            return;
+        const held = new Set(result.itemKeys ?? await lt.itemKeys(a.rowId));
+        if (!a.complete.keys.every((k) => held.has(k)))
+            return;
+        if (a.complete.then)
+            return this.apply(a.complete.then);
+        this.check(a, await lt.resolve(a.as, a.rowId, a.complete.payload ?? {}));
+        state.close(a.rowId);
+    }
+    check(a, result) {
+        const rowId = a.rowId;
+        if (result.outcome === escalations_1.VERB_OUTCOME.INVALID) {
+            this.d.log.error(log_1.GATEWAY_LOG.VERB_INVALID, { action: a.kind, row: rowId, detail: result.detail });
+        }
+        // Refused on a row the gateway holds open: outside the actor's roles (404) or claimed by someone else (409).
+        const open = rowId ? this.d.state.get(rowId) : undefined;
+        if (open && (result.status === NOT_FOUND || result.status === CONFLICT)) {
+            const event = result.status === NOT_FOUND ? log_1.GATEWAY_LOG.ROW_NOT_VISIBLE : log_1.GATEWAY_LOG.ROW_CLAIMED_ELSEWHERE;
+            this.d.log.warn(event, { action: a.kind, row: rowId, as: a.as, role: open.role, detail: result.detail });
+        }
+    }
+    async createAlarmRow(a) {
+        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;
+        }
+        // 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 });
+    }
+    /** Raise a quiet row for each connected machine silent longer than `quietMs`. */
+    checkQuiet(machineIds, quietMs) {
+        const now = Date.now();
+        for (const machineId of machineIds) {
+            const link = this.d.state.link(machineId);
+            if (!link.online || link.quietRowId || this.quietPending.has(machineId) || now - link.lastSeen < quietMs)
+                continue;
+            this.quietPending.add(machineId);
+            this.track(this.raiseQuiet(machineId, now - link.lastSeen).finally(() => this.quietPending.delete(machineId)));
+        }
+    }
+    async raiseQuiet(machineId, silentMs) {
+        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`,
+            metadata: { siteId: this.d.line.siteId, lineId: this.d.line.lineId, machineId, silentMs },
+        });
+        this.d.log.info(log_1.GATEWAY_LOG.QUIET_ROW, { row: id, machine: machineId });
+        this.d.state.link(machineId).quietRowId = id;
+    }
+    watchOffline(machineId) {
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            this.track(this.raiseOffline(machineId));
+        }, this.d.offlineDebounceMs);
+        this.timers.add(timer);
+    }
+    async raiseOffline(machineId) {
+        const link = this.d.state.links.get(machineId);
+        if (!link)
+            return;
+        link.watching = false;
+        if (link.online || link.rowId)
+            return;
+        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 },
+        });
+        this.d.log.info(log_1.GATEWAY_LOG.OFFLINE_ROW, { row: id, machine: machineId });
+        if (!link.online)
+            link.rowId = id;
+        else
+            await this.d.lt.resolve(actions_1.CONTROLLER, id, { decision: contracts_1.DECISION.RESTORED, note: `${machineId} back online` });
+    }
+}
+exports.Executor = Executor;

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

@@ -0,0 +1,82 @@
+/**
+ * The machine gateway: the seam between machines and escalation rows. It
+ * 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.
+ */
+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 { LineEscalations } from './escalations';
+import { type GatewayLog } from './log';
+import { GatewayState } from './state';
+export interface GatewaySettings {
+    topicRoot: string;
+    replyTimeoutMs: number;
+    dispatchAttempts: number;
+    offlineDebounceMs: number;
+    /** How long a dispatch stays valid at the machine (expiresAt). */
+    dispatchTtlMs: number;
+    /** A connected machine silent this long gets a quiet row; 0 turns the check off. */
+    quietMs: number;
+    /** How long confirmed message ids gather before a receipt goes out (codecs with receipts). */
+    receiptDelayMs?: number;
+}
+export interface GatewayDeps {
+    bus: MachineBus;
+    feed: EscalationFeed;
+    lt: LineEscalations;
+    line: LineDef;
+    settings: GatewaySettings;
+    log?: GatewayLog;
+    /** Reads a host's rows into handoffs; the standard handoff facets by default. */
+    rows?: HandoffRowAdapter;
+    /** The machines' wire protocol; the line protocol under `settings.topicRoot` by default. */
+    codec?: LineCodec;
+    /** Where a line that learns addresses keeps them; in memory by default. */
+    addresses?: AddressBook;
+}
+export declare class MachineGateway {
+    private readonly deps;
+    readonly state: GatewayState;
+    private readonly rows;
+    private readonly codec;
+    private readonly executor;
+    private readonly receipts;
+    private readonly log;
+    private readonly addresses;
+    private readonly admission;
+    private quietTimer?;
+    constructor(deps: GatewayDeps);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Resolves when no dispatch is in flight (tests). */
+    idle(): Promise<void>;
+    /**
+     * 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
+     * own alarm, offline and quiet rows, then the machines' retained state to
+     * catch what changed while no gateway was listening.
+     */
+    private reconcile;
+    /** Send waiting handoffs to machines that have room (pacing.ts). */
+    private pace;
+    private reconcileCommands;
+    private reconcileHandoffs;
+    private resync;
+    private onEscalation;
+    /**
+     * An event only says which row to look at. The row is read back as the
+     * controller, so a row on a role the line does not hold, or an event that
+     * disagrees with the stored row, does nothing.
+     */
+    private verify;
+    private onMachine;
+    /** A message the codec cannot read is not retried: it is logged and has no effect. */
+    private decode;
+    /** Done with the message: confirm each id its codec asked to confirm. */
+    private confirm;
+    private applyMachine;
+}

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

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * The machine gateway: the seam between machines and escalation rows. It
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MachineGateway = void 0;
+const rows_1 = require("../rows");
+const contracts_1 = require("../contracts");
+const actions_1 = require("./actions");
+const reconcile_1 = require("./reconcile");
+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 reply_waiter_1 = require("./reply-waiter");
+const executor_1 = require("./executor");
+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");
+class MachineGateway {
+    constructor(deps) {
+        this.deps = deps;
+        this.state = new state_1.GatewayState();
+        this.log = deps.log ?? log_1.consoleLog;
+        this.rows = deps.rows ?? rows_1.standardRows;
+        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.addresses = deps.addresses ?? new address_book_1.MemoryAddressBook();
+        this.executor = new executor_1.Executor({
+            addresses: this.addresses,
+            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 });
+    }
+    async start() {
+        await this.deps.bus.connect();
+        await this.deps.feed.connect();
+        await this.reconcile();
+        await this.deps.feed.consume((event) => this.onEscalation(event));
+        await this.deps.bus.consume((msg) => this.onMachine(msg));
+        const { quietMs } = this.deps.settings;
+        if (quietMs > 0) {
+            const machines = this.deps.line.machines.map((m) => m.machineId);
+            this.quietTimer = setInterval(() => this.executor.checkQuiet(machines, quietMs), Math.max(10, Math.floor(quietMs / 4)));
+        }
+        this.log.info(log_1.GATEWAY_LOG.STARTED, { site: this.deps.line.siteId, line: this.deps.line.lineId });
+    }
+    async stop() {
+        if (this.quietTimer)
+            clearInterval(this.quietTimer);
+        this.executor.stop();
+        await this.receipts.flush();
+        await this.deps.feed.close();
+        await this.deps.bus.close();
+    }
+    /** Resolves when no dispatch is in flight (tests). */
+    idle() {
+        return this.executor.idle();
+    }
+    /**
+     * 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
+     * own alarm, offline and quiet rows, then the machines' retained state to
+     * catch what changed while no gateway was listening.
+     */
+    async reconcile() {
+        // Handoffs wait until the whole line is read back, so pacing sees every job before it sends one.
+        this.state.holdDispatch = true;
+        try {
+            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));
+            const commands = await this.reconcileCommands();
+            const restored = await (0, reconcile_1.restoreLineRows)(this.state, this.deps.lt, this.deps.line);
+            await this.resync();
+            this.log.info(log_1.GATEWAY_LOG.RECONCILED, { handoffs, commands, addresses, ...restored });
+        }
+        finally {
+            this.state.holdDispatch = false;
+        }
+        await this.pace();
+    }
+    /** Send waiting handoffs to machines that have room (pacing.ts). */
+    async pace() {
+        await this.executor.apply((0, pacing_1.planPacing)(this.state, this.deps.line, this.deps.settings.dispatchTtlMs));
+    }
+    async reconcileCommands() {
+        let commands = 0;
+        for (const data of await this.deps.lt.listOpen({ type: contracts_1.ROW_TYPE.MACHINE_COMMAND })) {
+            const event = { type: 'reconcile', escalationId: data.id, role: data.role, verb: 'created', data };
+            const actions = (0, plan_escalation_1.planEscalationEvent)(this.state, this.deps.line, event, this.deps.settings.dispatchTtlMs, this.rows);
+            if (actions.length)
+                commands++;
+            await this.executor.apply(actions);
+        }
+        return commands;
+    }
+    async reconcileHandoffs() {
+        let handoffs = 0;
+        for (const query of this.rows.openRows(this.deps.line)) {
+            for (const data of await this.deps.lt.listOpen(query)) {
+                const event = { type: 'reconcile', escalationId: data.id, role: data.role, verb: 'created', data };
+                const actions = (0, plan_escalation_1.planEscalationEvent)(this.state, this.deps.line, event, this.deps.settings.dispatchTtlMs, this.rows);
+                if (this.state.get(data.id))
+                    handoffs++;
+                await this.executor.apply(actions);
+            }
+        }
+        return handoffs;
+    }
+    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);
+            }
+        }
+        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` } }]);
+        }
+    }
+    async onEscalation(event) {
+        try {
+            const verified = await this.verify(event);
+            if (verified)
+                await this.executor.apply((0, plan_escalation_1.planEscalationEvent)(this.state, this.deps.line, verified, this.deps.settings.dispatchTtlMs, this.rows));
+            await this.pace();
+            return transport_1.DISPOSITION.ACK;
+        }
+        catch (err) {
+            this.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { event: event.type, error: err.message });
+            return transport_1.DISPOSITION.NAK;
+        }
+    }
+    /**
+     * An event only says which row to look at. The row is read back as the
+     * controller, so a row on a role the line does not hold, or an event that
+     * disagrees with the stored row, does nothing.
+     */
+    async verify(event) {
+        if (!(0, plan_escalation_1.concernsLine)(this.state, this.deps.line, event, this.rows))
+            return null;
+        const row = await this.deps.lt.get(event.escalationId);
+        if (!row || !(0, plan_escalation_1.statusFits)(event.verb, row.status))
+            return null;
+        return { ...event, role: row.role, data: row };
+    }
+    async onMachine(msg) {
+        const decoded = this.decode(msg.topic, msg.payload, msg.retained);
+        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);
+                continue;
+            }
+            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 });
+            }
+            const applied = seen.violations.length && this.codec.strict
+                ? await (0, admission_1.holdViolation)(this.admission, msg, seen)
+                : await this.applyMachine(msg.topic, seen.parsed, seen.body);
+            failed ||= applied.failed;
+            outcome = worse(outcome, applied.disposition);
+        }
+        // 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) {
+            this.log.warn(log_1.GATEWAY_LOG.UNMATCHED, { topic: msg.topic, deliveries: msg.deliveries });
+            outcome = transport_1.DISPOSITION.TERM;
+        }
+        if (outcome !== transport_1.DISPOSITION.NAK)
+            this.confirm(acted);
+        return outcome;
+    }
+    /** A message the codec cannot read is not retried: it is logged and has no effect. */
+    decode(topic, payload, retained) {
+        try {
+            return this.codec.decode(topic, payload, retained);
+        }
+        catch (err) {
+            this.log.warn(log_1.GATEWAY_LOG.UNREADABLE, { topic, error: err.message });
+            return [];
+        }
+    }
+    /** Done with the message: confirm each id its codec asked to confirm. */
+    confirm(decoded) {
+        const seen = new Set();
+        for (const { parsed, receiptId } of decoded) {
+            if (!parsed || !receiptId || seen.has(receiptId))
+                continue;
+            seen.add(receiptId);
+            this.receipts.add(parsed.ident, receiptId);
+        }
+    }
+    async applyMachine(topic, parsed, body) {
+        let plan;
+        try {
+            plan = (0, plan_machine_1.planMachineMessage)(this.state, parsed, body, this.deps.settings.dispatchTtlMs);
+        }
+        catch (err) {
+            this.log.warn(log_1.GATEWAY_LOG.UNREADABLE, { topic, error: err.message });
+            return { disposition: transport_1.DISPOSITION.TERM, failed: false };
+        }
+        try {
+            await this.executor.apply(plan.actions);
+            await this.pace();
+            return { disposition: plan.disposition, failed: false };
+        }
+        catch (err) {
+            this.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic, error: err.message });
+            return { disposition: transport_1.DISPOSITION.NAK, failed: true };
+        }
+    }
+}
+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. */
+function worse(a, b) {
+    return RANK[b] > RANK[a] ? b : a;
+}

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

@@ -0,0 +1,10 @@
+export * from './actions';
+export * from './escalations';
+export * from './gateway';
+export * from './log';
+export * from './lt-http';
+export * from './api-escalations';
+export * from './provision';
+export * from './state';
+export * from './address-book';
+export * from './registration';

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

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./actions"), exports);
+__exportStar(require("./escalations"), exports);
+__exportStar(require("./gateway"), exports);
+__exportStar(require("./log"), exports);
+__exportStar(require("./lt-http"), exports);
+__exportStar(require("./api-escalations"), exports);
+__exportStar(require("./provision"), exports);
+__exportStar(require("./state"), exports);
+__exportStar(require("./address-book"), exports);
+__exportStar(require("./registration"), exports);

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

@@ -0,0 +1,16 @@
+/**
+ * How a handoff's units become machine jobs. A codec that takes one unit per
+ * dispatch gets one job per unit, each with its own job id and command id;
+ * otherwise the units travel as one job. The split is deterministic, so a
+ * cancel or a re-dispatch names the same jobs the dispatch did.
+ */
+import type { HandoffUnit } from '../contracts';
+export interface DispatchJob {
+    jobId: string;
+    units: HandoffUnit[];
+    /** Appended to command ids so each job's reply is told apart; empty when unsplit. */
+    suffix: string;
+}
+/** Whether a machine's job id is `jobId` or one of the jobs it was split into, whichever units a row names. */
+export declare function jobOwns(jobId: string, reported: string): boolean;
+export declare function dispatchJobs(jobId: string, units: HandoffUnit[], perDispatch: number | null): DispatchJob[];

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

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * How a handoff's units become machine jobs. A codec that takes one unit per
+ * dispatch gets one job per unit, each with its own job id and command id;
+ * otherwise the units travel as one job. The split is deterministic, so a
+ * cancel or a re-dispatch names the same jobs the dispatch did.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobOwns = jobOwns;
+exports.dispatchJobs = dispatchJobs;
+/** Whether a machine's job id is `jobId` or one of the jobs it was split into, whichever units a row names. */
+function jobOwns(jobId, reported) {
+    return reported === jobId || reported.startsWith(`${jobId}#`);
+}
+function dispatchJobs(jobId, units, perDispatch) {
+    if (!perDispatch || units.length <= perDispatch)
+        return [{ jobId, units, suffix: '' }];
+    const jobs = [];
+    for (let i = 0; i < units.length; i += perDispatch) {
+        const n = jobs.length + 1;
+        jobs.push({ jobId: `${jobId}#${n}`, units: units.slice(i, i + perDispatch), suffix: `#${n}` });
+    }
+    return jobs;
+}

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

@@ -0,0 +1,41 @@
+export declare const GATEWAY_LOG: {
+    readonly STARTED: "machine_gateway.started";
+    readonly RECONCILED: "machine_gateway.reconciled";
+    readonly DISPATCHED: "machine_gateway.dispatch.accepted";
+    readonly DISPATCH_REFUSED: "machine_gateway.dispatch.refused";
+    readonly DISPATCH_READY: "machine_gateway.dispatch.ready";
+    readonly DISPATCH_FAILED: "machine_gateway.dispatch.failed";
+    readonly DISPATCH_RECONCILED: "machine_gateway.dispatch.reconciled";
+    readonly VERB_INVALID: "machine_gateway.verb.invalid";
+    readonly VERB_FAILED: "machine_gateway.verb.failed";
+    readonly ROW_NOT_VISIBLE: "machine_gateway.verb.row_not_visible";
+    readonly ROW_CLAIMED_ELSEWHERE: "machine_gateway.verb.row_claimed_elsewhere";
+    readonly UNMATCHED: "machine_gateway.message.unmatched";
+    readonly UNREADABLE: "machine_gateway.message.unreadable";
+    readonly CONTRACT_VIOLATION: "machine_gateway.contract.violation";
+    readonly VIOLATION_ROW: "machine_gateway.contract.row_created";
+    readonly ADDRESS_BOUND: "machine_gateway.address.bound";
+    readonly ADDRESS_CONTESTED: "machine_gateway.address.contested";
+    readonly ADDRESS_UNKNOWN: "machine_gateway.address.unknown";
+    readonly ADDRESS_REFUSED: "machine_gateway.address.refused";
+    readonly RECEIPT_FAILED: "machine_gateway.receipt.failed";
+    readonly ALARM_ROW: "machine_gateway.alarm.row_created";
+    readonly OFFLINE_ROW: "machine_gateway.offline.row_created";
+    readonly QUIET_ROW: "machine_gateway.quiet.row_created";
+    readonly COMMANDED: "machine_gateway.command.accepted";
+    readonly COMMAND_REFUSED: "machine_gateway.command.refused";
+    readonly COMMAND_UNANSWERED: "machine_gateway.command.unanswered";
+    readonly COMMAND_UNSUPPORTED: "machine_gateway.command.unsupported";
+    readonly LEADING: "machine_gateway.line.leading";
+    readonly STANDBY: "machine_gateway.line.standby";
+    readonly LEADERSHIP_LOST: "machine_gateway.line.leadership_lost";
+    readonly START_FAILED: "machine_gateway.line.start_failed";
+};
+export type GatewayLogEvent = typeof GATEWAY_LOG[keyof typeof GATEWAY_LOG];
+export interface GatewayLog {
+    info(event: GatewayLogEvent, context?: Record<string, unknown>): void;
+    warn(event: GatewayLogEvent, context?: Record<string, unknown>): void;
+    error(event: GatewayLogEvent, context?: Record<string, unknown>): void;
+}
+export declare const consoleLog: GatewayLog;
+export declare const silentLog: GatewayLog;