@hotmeshio/long-tail 0.25.3 → 0.26.0

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

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Machine messages to gateway actions: the escalation verbs a person would
+ * perform, performed for the machine. Each unit's arrival and the sender's
+ * finished record accumulate on the handoff row, and the last expected item
+ * resolves it. A failure on either side resolves it with an error. Alarms that
+ * stop work and machines that go dark or quiet become rows for people. A
+ * restarted machine gets back the dispatches it lost. Everything else stays
+ * in the stream.
+ *
+ * A message whose row does not exist yet is nak'd and arrives again; one whose
+ * row already closed is acked, so a replay never resolves anything twice.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planMachineMessage = planMachineMessage;
+const contracts_1 = require("../contracts");
+const protocol_1 = require("../../../lib/machines/protocol");
+const transport_1 = require("../../../lib/machines/transport");
+const escalation_1 = require("../../../types/escalation");
+const actions_1 = require("./actions");
+const pacing_1 = require("./pacing");
+const plan_shared_1 = require("./plan-shared");
+const jobs_1 = require("./jobs");
+const trace_1 = require("./trace");
+const state_1 = require("./state");
+const ack = (actions = []) => ({ actions, disposition: transport_1.DISPOSITION.ACK });
+const nak = { actions: [], disposition: transport_1.DISPOSITION.NAK };
+function planMachineMessage(state, parsed, env, dispatchTtlMs) {
+    const m = parsed.ident.machineId;
+    const b = env?.body ?? {};
+    const plan = planByKind(state, m, parsed, env, b, dispatchTtlMs);
+    return { ...plan, actions: [...heard(state, m), ...plan.actions] };
+}
+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 }]);
+        case protocol_1.MESSAGE_KIND.JOB:
+            return planJob(state, m, b, env?.at, ttl);
+        case protocol_1.MESSAGE_KIND.ALARM:
+            return planAlarm(state, parsed, parsed.key ?? b.alarmId, env);
+        case protocol_1.MESSAGE_KIND.PRESENCE:
+            return planPresence(state, m, b);
+        case protocol_1.MESSAGE_KIND.SNAPSHOT:
+            return planSnapshot(state, m, b, ttl);
+        default:
+            return ack();
+    }
+}
+/** Any message proves a quiet machine is talking again. */
+function heard(state, m) {
+    const link = state.link(m);
+    link.lastSeen = Date.now();
+    if (!link.quietRowId)
+        return [];
+    const rowId = link.quietRowId;
+    link.quietRowId = undefined;
+    return [{ kind: 'resolve', as: actions_1.CONTROLLER, rowId, payload: { decision: contracts_1.DECISION.RESTORED, note: `${m} is talking again` } }];
+}
+/** Ack when the matching row already closed (a replay or a cancel); otherwise wait for the row. */
+function missing(state, unitId, pred) {
+    return state.closedFor(unitId, pred) ? ack() : nak;
+}
+/** Whether a machine's job id belongs to `jobId`; a row for some of a job's units still owns it. */
+function ownsJob(jobId, reported) {
+    if (!jobId || typeof reported !== 'string')
+        return true;
+    return (0, jobs_1.jobOwns)(jobId, reported);
+}
+/** Keep the receiver's arrival event for the unit, to go out with its dispatch. */
+function withArrival(row, unitId, b) {
+    row.arrivals = { ...row.arrivals, [unitId]: b };
+    return row;
+}
+function planJob(state, m, b, at, ttl) {
+    const unitId = b.unitId;
+    // An event from an earlier attempt's job never touches a later attempt's row.
+    const toHere = (r) => r.toMachine === m && ownsJob(r.jobId, b.jobId);
+    const fromHere = (r) => r.fromMachine === m && ownsJob(r.senderJobId, b.jobId);
+    if (b.event === protocol_1.JOB_EVENT.ARRIVED) {
+        const row = state.openFor(unitId, toHere);
+        if (!row)
+            return missing(state, unitId, toHere);
+        const expected = row.units.find((u) => u.unitId === unitId)?.carrierId;
+        if (expected && b.carrierId && expected !== b.carrierId) {
+            return ack((0, plan_shared_1.failHandoff)(state, row, m, {
+                received: false, unitId, errorCode: contracts_1.HANDOFF_ERROR.CARRIER_MISMATCH, detail: `${m} read carrier ${b.carrierId}, expected ${expected}`,
+            }));
+        }
+        // The unit is at the receiver now, and off the sender.
+        const job = (0, jobs_1.dispatchJobs)(row.jobId, row.units, state.unitsPerDispatch).find((j) => j.units.some((u) => u.unitId === unitId));
+        if (job)
+            state.hold(m, unitId, job.jobId);
+        const early = row.fromMachine ? releasedEarly(state, row, unitId) : [];
+        if (row.fromMachine)
+            state.letGo(row.fromMachine, unitId);
+        const units = row.units.map((u) => u.unitId);
+        const complete = row.dispatch === state_1.DISPATCH_STATE.ARRIVING
+            ? { keys: units.map(contracts_1.itemKeys.arrived), then: [(0, pacing_1.dispatchAction)(withArrival(row, unitId, b), m, ttl)] }
+            : { keys: units.map(contracts_1.itemKeys.arrived), payload: { received: true, receiver: m, units } };
+        return ack([...early, {
+                kind: 'accumulate', as: m, rowId: row.id, itemKey: contracts_1.itemKeys.arrived(unitId),
+                payload: {
+                    unitId, carrierId: b.carrierId ?? null, from: b.peer ?? null, at: at ?? new Date().toISOString(),
+                    ...(row.dispatch === state_1.DISPATCH_STATE.ARRIVING ? { arrival: b } : {}),
+                },
+                complete,
+            }]);
+    }
+    if (b.event === protocol_1.JOB_EVENT.FINISHED) {
+        const row = state.openFor(unitId, fromHere);
+        if (!row) {
+            if (!state.closedFor(unitId, fromHere))
+                state.rememberFinish(m, unitId, b);
+            return missing(state, unitId, fromHere);
+        }
+        state.takeFinish(m, unitId);
+        const released = releasedAction(row, m, b);
+        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})` : ''}`,
+            })]);
+    }
+    if (b.event === protocol_1.JOB_EVENT.TRANSFER_FAILED) {
+        const either = (r) => toHere(r) || fromHere(r);
+        const row = state.openFor(unitId, either);
+        if (!row)
+            return missing(state, unitId, either);
+        return ack((0, plan_shared_1.failHandoff)(state, row, m, { received: false, unitId, errorCode: b.failure, detail: `${m} reported ${b.failure}` }));
+    }
+    if (b.event === protocol_1.JOB_EVENT.RELEASED) {
+        state.letGo(m, unitId);
+        return ack();
+    }
+    if (b.event === protocol_1.JOB_EVENT.WITHDRAWN) {
+        state.letGo(m, unitId);
+        const row = state.openFor(unitId, toHere);
+        if (!row)
+            return ack();
+        return ack((0, plan_shared_1.failHandoff)(state, row, m, { received: false, unitId, errorCode: contracts_1.HANDOFF_ERROR.WITHDRAWN, detail: `${m} gave up ${b.jobId}` }));
+    }
+    return ack();
+}
+function releasedAction(row, m, b) {
+    row.trace = (0, trace_1.mergeTrace)(row.trace, [(0, trace_1.traceEntry)(m, b)]);
+    return { kind: 'accumulate', as: m, rowId: row.id, itemKey: contracts_1.itemKeys.released(b.unitId), payload: b, metadata: (0, trace_1.traceFacets)(row.trace) };
+}
+/** The sender's finished record that came before the row, written ahead of the arrival that may resolve it. */
+function releasedEarly(state, row, unitId) {
+    const b = state.takeFinish(row.fromMachine, unitId);
+    if (!b || b.result !== protocol_1.JOB_RESULT.OK || !ownsJob(row.senderJobId, b.jobId))
+        return [];
+    return [releasedAction(row, row.fromMachine, b)];
+}
+function planAlarm(state, parsed, alarmId, env) {
+    const { siteId, lineId, machineId: m } = parsed.ident;
+    const key = state.alarmKey(m, alarmId);
+    const b = env?.body ?? {};
+    if (!env || b.active === false) {
+        const track = state.alarms.get(key);
+        state.alarms.delete(key);
+        if (!track?.rowId || !track.open)
+            return ack();
+        return ack([{
+                kind: 'resolve', as: actions_1.CONTROLLER, rowId: track.rowId,
+                payload: { decision: contracts_1.DECISION.CLEARED, clearedBy: b.clearedBy ?? null, note: `cleared at ${m}${b.clearedBy ? ` by ${b.clearedBy}` : ''}` },
+            }]);
+    }
+    if (!protocol_1.STOPPING_LEVELS.includes(b.level))
+        return ack();
+    const known = state.alarms.get(key);
+    if (known && (!known.raisedAt || !b.raisedAt || known.raisedAt === b.raisedAt))
+        return ack();
+    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` } }]
+        : [];
+    state.alarms.set(key, { machineId: m, alarmId, raisedAt: b.raisedAt, open: true });
+    return ack([...superseded, {
+            kind: 'createAlarmRow', machineId: m, alarmId,
+            row: {
+                type: contracts_1.ROW_TYPE.ALARM, subtype: b.level, role: contracts_1.LINE_ROLE.OPERATOR, priority: b.level === protocol_1.LEVEL.EMERGENCY ? 1 : 2,
+                description: `${m}: ${b.text}`,
+                metadata: {
+                    siteId, lineId, machineId: m, alarmId, code: b.code, level: b.level, raisedAt: b.raisedAt,
+                    zone: b.zone ?? null, autoClears: b.autoClears ?? false, action: b.action ?? null, jobId: b.jobId ?? null,
+                },
+                ...catalogEnvelope(b.catalog),
+            },
+        }]);
+}
+/** An alarm naming the catalog edition its code comes from carries that edition as a lookup, so the row reads its meaning. */
+function catalogEnvelope(catalog) {
+    const ref = catalog;
+    if (!ref || typeof ref.domain !== 'string' || typeof ref.key !== 'string')
+        return {};
+    return { envelope: JSON.stringify({ [escalation_1.ESCALATION_ENVELOPE_KEYS.LOOKUPS]: [ref] }) };
+}
+function planPresence(state, m, b) {
+    const link = state.link(m);
+    if (b.online !== true) {
+        if (link.online)
+            link.since = Date.now();
+        link.online = false;
+        if (link.rowId || link.watching)
+            return ack();
+        link.watching = true;
+        return ack([{ kind: 'watchOffline', machineId: m }]);
+    }
+    if (b.software)
+        link.software = b.software;
+    const wasOffline = !link.online;
+    link.online = true;
+    link.watching = false;
+    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 (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;
+    }
+    return ack(actions);
+}
+/** A new boot id means the machine restarted and lost its queue: send its open dispatches again. */
+function planSnapshot(state, m, b, ttl) {
+    const link = state.link(m);
+    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))
+        state.keepHeld(m, new Set(jobIds));
+    const answer = { kind: 'settleSnapshot', machineId: m, jobIds };
+    const previous = link.bootId;
+    link.bootId = b.bootId;
+    if (!previous || previous === b.bootId)
+        return ack([answer]);
+    const held = new Set(jobIds);
+    const missing = (r) => (0, jobs_1.dispatchJobs)(r.jobId, r.units, state.unitsPerDispatch).some((j) => !held.has(j.jobId));
+    const lost = state.open().filter((r) => r.toMachine === m && r.dispatch === state_1.DISPATCH_STATE.ACCEPTED && missing(r));
+    return ack([answer, ...lost.map((r) => (0, pacing_1.dispatchAction)(r, m, ttl))]);
+}

package/build/services/machines/gateway/plan-shared.d.ts

@@ -0,0 +1,18 @@
+import { type HandoffResolution } from '../contracts';
+import type { Action, Actor } from './actions';
+import { type DispatchJob } from './jobs';
+import { type GatewayState, type HandoffRow } from './state';
+/** A cancel for each job a handoff's units became at `machineId`, or for those `keep` leaves out. */
+export declare function cancelJobs(state: GatewayState, row: HandoffRow, machineId: string, jobId: string, tag?: string, keep?: (job: DispatchJob) => boolean): Action[];
+/**
+ * Withdraw a dispatch that may still sit in the receiver's queue. A job some
+ * of whose units already reached the receiver is under way: it stays, and
+ * what happens to it is the workflow's next decision (a machine-command row).
+ */
+export declare function cancelDispatch(state: GatewayState, row: HandoffRow): Action[];
+/**
+ * End a handoff without a receipt: resolve it with the error, then withdraw the
+ * dispatch. A row the receiver has claimed is resolved by the receiver (only the
+ * claimant may resolve a claimed row); `reportedBy` names who saw the failure.
+ */
+export declare function failHandoff(state: GatewayState, row: HandoffRow, reporter: Actor, resolution: HandoffResolution): Action[];

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cancelJobs = cancelJobs;
+exports.cancelDispatch = cancelDispatch;
+exports.failHandoff = failHandoff;
+const contracts_1 = require("../contracts");
+const protocol_1 = require("../../../lib/machines/protocol");
+const jobs_1 = require("./jobs");
+const state_1 = require("./state");
+/** A cancel for each job a handoff's units became at `machineId`, or for those `keep` leaves out. */
+function cancelJobs(state, row, machineId, jobId, tag = '', keep = () => false) {
+    return (0, jobs_1.dispatchJobs)(jobId, row.units, state.unitsPerDispatch).filter((job) => !keep(job)).map((job) => ({
+        kind: 'command', machineId, op: protocol_1.OP.CANCEL, cmdId: `${(0, contracts_1.cancelCommandId)(row.id)}${tag}${job.suffix}`, args: { jobId: job.jobId },
+    }));
+}
+/**
+ * Withdraw a dispatch that may still sit in the receiver's queue. A job some
+ * of whose units already reached the receiver is under way: it stays, and
+ * what happens to it is the workflow's next decision (a machine-command row).
+ */
+function cancelDispatch(state, row) {
+    const to = row.toMachine;
+    if (!to || row.dispatch === state_1.DISPATCH_STATE.NONE || row.dispatch === state_1.DISPATCH_STATE.REFUSED)
+        return [];
+    return cancelJobs(state, row, to, row.jobId, '', (job) => job.units.some((u) => state.heldJob(to, u.unitId) === job.jobId));
+}
+/**
+ * End a handoff without a receipt: resolve it with the error, then withdraw the
+ * dispatch. A row the receiver has claimed is resolved by the receiver (only the
+ * claimant may resolve a claimed row); `reportedBy` names who saw the failure.
+ */
+function failHandoff(state, row, reporter, resolution) {
+    const claimant = row.dispatch === state_1.DISPATCH_STATE.ACCEPTED && row.toMachine ? row.toMachine : reporter;
+    const payload = claimant === reporter ? { ...resolution } : { ...resolution, reportedBy: reporter };
+    return [{ kind: 'resolve', as: claimant, rowId: row.id, payload }, ...cancelDispatch(state, row)];
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Identities. Each machine acts in Long Tail as its own bot account, so the
+ * rows it claims and resolves name the machine beside the people who worked
+ * the unit; the gateway's own bot (the controller) raises operator rows. At
+ * boot the gateway logs in, makes sure every bot exists with its roles, and
+ * mints a fresh session key per bot, revoking the previous one.
+ */
+import { type LineDef } from '../../../lib/machines/line';
+import { type Actor } from './actions';
+import type { LtHttp } from './lt-http';
+export declare const SESSION_KEY_NAME = "machine-gateway-session";
+export interface Identity {
+    actor: Actor;
+    botName: string;
+    roles: string[];
+}
+/** The bots a line needs: one per machine, plus the controller. */
+export declare function lineIdentities(line: LineDef): Identity[];
+/** A builder token: LT_GATEWAY_TOKEN when set, otherwise a username/password login. */
+export declare function adminToken(http: LtHttp, env: Record<string, string | undefined>): Promise<string>;
+/** Ensure every bot and mint its session key; returns actor → bearer token. */
+export declare function provisionIdentities(http: LtHttp, admin: string, line: LineDef): Promise<Map<Actor, string>>;

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

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Identities. Each machine acts in Long Tail as its own bot account, so the
+ * rows it claims and resolves name the machine beside the people who worked
+ * the unit; the gateway's own bot (the controller) raises operator rows. At
+ * boot the gateway logs in, makes sure every bot exists with its roles, and
+ * mints a fresh session key per bot, revoking the previous one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_KEY_NAME = void 0;
+exports.lineIdentities = lineIdentities;
+exports.adminToken = adminToken;
+exports.provisionIdentities = provisionIdentities;
+const protocol_1 = require("../../../lib/machines/protocol");
+const line_1 = require("../../../lib/machines/line");
+const actions_1 = require("./actions");
+exports.SESSION_KEY_NAME = 'machine-gateway-session';
+/** The bots a line needs: one per machine, plus the controller. */
+function lineIdentities(line) {
+    const stations = (0, line_1.stationRoles)(line);
+    const machines = line.machines.map((m) => ({
+        actor: m.machineId,
+        botName: `machine-${(0, protocol_1.clientIdOf)((0, line_1.identOf)(line, m.machineId))}`,
+        roles: [...stations, ...(0, line_1.receiverRoles)(line)],
+    }));
+    const controller = {
+        actor: actions_1.CONTROLLER,
+        botName: (0, line_1.controllerId)(line),
+        roles: [...stations, ...(0, line_1.receiverRoles)(line), (0, line_1.operatorRole)(line)],
+    };
+    return [controller, ...machines];
+}
+/** A builder token: LT_GATEWAY_TOKEN when set, otherwise a username/password login. */
+async function adminToken(http, env) {
+    if (env.LT_GATEWAY_TOKEN)
+        return env.LT_GATEWAY_TOKEN;
+    const username = env.LT_GATEWAY_USERNAME;
+    const password = env.LT_GATEWAY_PASSWORD;
+    if (!username || !password)
+        throw new Error('the gateway needs LT_GATEWAY_TOKEN, or LT_GATEWAY_USERNAME and LT_GATEWAY_PASSWORD');
+    const { token } = await http.request('POST', '/auth/login', null, { username, password });
+    return token;
+}
+async function ensureBot(http, admin, identity) {
+    const page = await http.request('GET', `/bot-accounts?search=${encodeURIComponent(identity.botName)}&limit=50`, admin);
+    const found = page.bots.find((b) => b.external_id === identity.botName);
+    if (found) {
+        const { roles } = await http.request('GET', `/bot-accounts/${found.id}/roles`, admin);
+        const held = new Set(roles.map((r) => r.role));
+        for (const role of identity.roles.filter((r) => !held.has(r))) {
+            await http.request('POST', `/bot-accounts/${found.id}/roles`, admin, { role, type: 'member' });
+        }
+        return found.id;
+    }
+    const bot = await http.request('POST', '/bot-accounts', admin, {
+        name: identity.botName,
+        display_name: identity.actor === actions_1.CONTROLLER ? 'Line controller' : identity.actor,
+        description: identity.actor === actions_1.CONTROLLER ? 'Machine gateway: raises line-operator rows' : `Machine ${identity.actor} on the line`,
+        roles: identity.roles.map((role) => ({ role, type: 'member' })),
+    });
+    return bot.id;
+}
+async function mintSessionKey(http, admin, botId) {
+    const { keys } = await http.request('GET', `/bot-accounts/${botId}/api-keys`, admin);
+    for (const key of keys.filter((k) => k.name === exports.SESSION_KEY_NAME)) {
+        await http.request('DELETE', `/bot-accounts/${botId}/api-keys/${key.id}`, admin);
+    }
+    const { rawKey } = await http.request('POST', `/bot-accounts/${botId}/api-keys`, admin, { name: exports.SESSION_KEY_NAME });
+    return rawKey;
+}
+/** Ensure every bot and mint its session key; returns actor → bearer token. */
+async function provisionIdentities(http, admin, line) {
+    const tokens = new Map();
+    for (const identity of lineIdentities(line)) {
+        const botId = await ensureBot(http, admin, identity);
+        tokens.set(identity.actor, await mintSessionKey(http, admin, botId));
+    }
+    return tokens;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Application receipts. A machine that keeps an outbox until the line
+ * controller confirms each event gets that confirmation here: once the
+ * gateway is done with a message, its id joins a batch for that machine, and
+ * the batch goes out through the codec after a short delay or when full. A
+ * replayed event is confirmed again, so a machine that missed a receipt stops
+ * resending.
+ */
+import { type LineCodec, type MachineIdent } from '../../../lib/machines/protocol';
+import type { MachineBus } from '../../../lib/machines/transport';
+import { type GatewayLog } from './log';
+/** Most message ids one receipt carries. */
+export declare const MAX_RECEIPT_IDS = 100;
+export interface ReceiptDeps {
+    bus: MachineBus;
+    codec: Pick<LineCodec, 'receipt'>;
+    /** How long ids gather before a receipt goes out. */
+    delayMs: number;
+    log: GatewayLog;
+}
+export declare class ReceiptBatcher {
+    private readonly d;
+    private batches;
+    private sending;
+    constructor(d: ReceiptDeps);
+    /** Whether the codec sends receipts at all. */
+    get enabled(): boolean;
+    add(ident: MachineIdent, messageId: string): void;
+    /** Send every batch now and wait for the sends. */
+    flush(): Promise<void>;
+    private send;
+    private publish;
+}

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

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Application receipts. A machine that keeps an outbox until the line
+ * controller confirms each event gets that confirmation here: once the
+ * gateway is done with a message, its id joins a batch for that machine, and
+ * the batch goes out through the codec after a short delay or when full. A
+ * replayed event is confirmed again, so a machine that missed a receipt stops
+ * resending.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReceiptBatcher = exports.MAX_RECEIPT_IDS = void 0;
+const protocol_1 = require("../../../lib/machines/protocol");
+const log_1 = require("./log");
+/** Most message ids one receipt carries. */
+exports.MAX_RECEIPT_IDS = 100;
+class ReceiptBatcher {
+    constructor(d) {
+        this.d = d;
+        this.batches = new Map();
+        this.sending = new Set();
+    }
+    /** Whether the codec sends receipts at all. */
+    get enabled() {
+        return !!this.d.codec.receipt;
+    }
+    add(ident, messageId) {
+        if (!this.enabled)
+            return;
+        const key = (0, protocol_1.addressOf)(ident);
+        let batch = this.batches.get(key);
+        if (!batch) {
+            batch = { ident, ids: new Set() };
+            this.batches.set(key, batch);
+        }
+        batch.ids.add(messageId);
+        if (batch.ids.size >= exports.MAX_RECEIPT_IDS)
+            this.send(key);
+        else
+            batch.timer ??= setTimeout(() => this.send(key), this.d.delayMs);
+    }
+    /** Send every batch now and wait for the sends. */
+    async flush() {
+        for (const key of [...this.batches.keys()])
+            this.send(key);
+        await Promise.all([...this.sending]);
+    }
+    send(key) {
+        const batch = this.batches.get(key);
+        if (!batch)
+            return;
+        this.batches.delete(key);
+        if (batch.timer)
+            clearTimeout(batch.timer);
+        const ids = [...batch.ids];
+        const work = this.publish(batch.ident, ids)
+            .catch((err) => this.d.log.warn(log_1.GATEWAY_LOG.RECEIPT_FAILED, { machine: batch.ident.machineId, ids: ids.length, error: String(err?.message ?? err) }))
+            .finally(() => this.sending.delete(work));
+        this.sending.add(work);
+    }
+    async publish(ident, ids) {
+        for (const wire of this.d.codec.receipt(ident, ids))
+            await this.d.bus.publish(wire.topic, wire.payload);
+    }
+}
+exports.ReceiptBatcher = ReceiptBatcher;

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

@@ -0,0 +1,33 @@
+/**
+ * What a gateway restores when it starts leading a line, read back from Long
+ * Tail: the alarm, offline and quiet rows it raised before, so a clear or a
+ * return that comes later still resolves them; and the units each open
+ * handoff saw arrive, so the receiver holds them again.
+ */
+import { type LineDef } from '../../../lib/machines/line';
+import type { AddressBook } from './address-book';
+import type { Action } from './actions';
+import type { LineEscalations } from './escalations';
+import { type GatewayState } from './state';
+export interface RestoredRows {
+    alarms: number;
+    offline: number;
+    quiet: number;
+    registrations: number;
+}
+export declare function restoreLineRows(state: GatewayState, lt: LineEscalations, line: LineDef): Promise<RestoredRows>;
+/** The addresses the line learned before, for the stations that still learn theirs. */
+export declare function restoreAddresses(state: GatewayState, book: AddressBook, line: LineDef): Promise<number>;
+/** Alarm rows whose alarm the machine no longer holds: it cleared while no gateway was listening. */
+export declare function alarmsClearedMeanwhile(state: GatewayState, active: Set<string>): {
+    key: string;
+    rowId: string;
+    machineId: string;
+}[];
+/**
+ * Units that arrived at an open handoff's receiver, read from the row's items:
+ * the receiver holds them again, so a timeout leaves their job alone. A row
+ * whose units all arrived completes; one dispatched on arrival is sent with the
+ * arrivals it holds.
+ */
+export declare function arrivalsOnRows(state: GatewayState, lt: LineEscalations, dispatchTtlMs: number): Promise<Action[]>;

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

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * What a gateway restores when it starts leading a line, read back from Long
+ * Tail: the alarm, offline and quiet rows it raised before, so a clear or a
+ * return that comes later still resolves them; and the units each open
+ * handoff saw arrive, so the receiver holds them again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restoreLineRows = restoreLineRows;
+exports.restoreAddresses = restoreAddresses;
+exports.alarmsClearedMeanwhile = alarmsClearedMeanwhile;
+exports.arrivalsOnRows = arrivalsOnRows;
+const contracts_1 = require("../contracts");
+const line_1 = require("../../../lib/machines/line");
+const jobs_1 = require("./jobs");
+const pacing_1 = require("./pacing");
+const state_1 = require("./state");
+async function restoreLineRows(state, lt, line) {
+    const role = (0, line_1.operatorRole)(line);
+    const mine = (row) => row.metadata?.siteId === line.siteId && row.metadata?.lineId === line.lineId && row.metadata?.machineId;
+    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 });
+    }
+    for (const row of offline) {
+        const link = state.link(row.metadata.machineId);
+        link.online = false;
+        link.rowId = row.id;
+    }
+    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);
+    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. */
+async function restoreAddresses(state, book, line) {
+    let restored = 0;
+    for (const [machineId, address] of await book.load()) {
+        if (!(0, line_1.learnsAddress)(line, machineId))
+            continue;
+        state.bindAddress(machineId, address);
+        restored++;
+    }
+    return restored;
+}
+/** Alarm rows whose alarm the machine no longer holds: it cleared while no gateway was listening. */
+function alarmsClearedMeanwhile(state, active) {
+    return [...state.alarms.entries()]
+        .filter(([key, t]) => t.open && t.rowId && !active.has(key))
+        .map(([key, t]) => ({ key, rowId: t.rowId, machineId: t.machineId }));
+}
+/**
+ * Units that arrived at an open handoff's receiver, read from the row's items:
+ * the receiver holds them again, so a timeout leaves their job alone. A row
+ * whose units all arrived completes; one dispatched on arrival is sent with the
+ * arrivals it holds.
+ */
+async function arrivalsOnRows(state, lt, dispatchTtlMs) {
+    const actions = [];
+    for (const row of state.open()) {
+        const to = row.toMachine;
+        if (!to || (row.dispatch !== state_1.DISPATCH_STATE.ARRIVING && row.dispatch !== state_1.DISPATCH_STATE.ACCEPTED))
+            continue;
+        const items = await lt.items(row.id);
+        const units = row.units.map((u) => u.unitId);
+        const { arrived, missing } = (0, contracts_1.handoffProgress)(units, items);
+        for (const job of (0, jobs_1.dispatchJobs)(row.jobId, row.units, state.unitsPerDispatch)) {
+            for (const u of job.units)
+                if (arrived.includes(u.unitId))
+                    state.hold(to, u.unitId, job.jobId);
+        }
+        if (missing.length)
+            continue;
+        if (row.dispatch === state_1.DISPATCH_STATE.ACCEPTED) {
+            actions.push({ kind: 'resolve', as: to, rowId: row.id, payload: { received: true, receiver: to, units } });
+            continue;
+        }
+        const byUnit = new Map(items.filter((i) => (0, contracts_1.arrivedUnit)(i.itemKey)).map((i) => [i.payload.unitId, i.payload]));
+        row.arrivals = Object.fromEntries(units.map((u) => [u, byUnit.get(u)?.arrival ?? { unitId: u, carrierId: byUnit.get(u)?.carrierId ?? null }]));
+        actions.push((0, pacing_1.dispatchAction)(row, to, dispatchTtlMs));
+    }
+    return actions;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Learned addresses. On a line that learns them, a station is bound to the
+ * address that first claims it. A claim that disagrees with a binding (a
+ * station already bound to another address, or an address bound to another
+ * station) is a person's decision: one registration row per claim, and the
+ * claimant's messages have no effect until it is approved. Lines that declare
+ * their addresses pass through unchanged.
+ */
+import { type LineDef } from '../../../lib/machines/line';
+import { type Inspection, type MachineIdent } from '../../../lib/machines/protocol';
+import type { EscalationEvent } from '../../../lib/machines/transport';
+import type { Action, CreateRowInput } from './actions';
+import type { GatewayState } from './state';
+export declare const SENDER: {
+    readonly KNOWN: "known";
+    readonly BOUND: "bound";
+    readonly CONTESTED: "contested";
+    readonly UNKNOWN: "unknown";
+};
+export type SenderStatus = typeof SENDER[keyof typeof SENDER];
+export interface Sender {
+    status: SenderStatus;
+    address: string;
+    /** The station the message is from (known, bound) or claims to be (contested). */
+    machineId?: string;
+    /** The inspection with the station as its machine id; set when the message may be acted on. */
+    seen?: Inspection;
+}
+/** Who sent a message: a known station, one bound just now, a contested claim, or no station at all. */
+export declare function resolveSender(state: GatewayState, line: LineDef, seen: Inspection): Sender;
+/** A station's identity on the wire, with the address the line learned for it. */
+export declare function identFor(state: GatewayState, line: LineDef, machineId: string): MachineIdent;
+/** Whether the gateway knows where to send to a station: a declared address, or one it learned. */
+export declare function reachable(state: GatewayState, line: LineDef, machineId: string): boolean;
+/** The row asking a person whether `address` is `machineId`. */
+export declare function registrationRow(state: GatewayState, line: LineDef, address: string, machineId: string): CreateRowInput;
+/** A person decided a registration row: approval binds the station to the claimant; anything else leaves the binding. */
+export declare function planRegistrationRow(state: GatewayState, line: LineDef, event: EscalationEvent): Action[];