@hotmeshio/long-tail 0.25.4 → 0.27.0

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

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Escalation events to gateway actions. A new handoff row for a machine is the
+ * cue to dispatch, exactly as a new row is the cue for a person to look at the
+ * dashboard. A cancelled or expired row withdraws its dispatch; a row commands
+ * only the machine whose role it is parked on, so the sender's job is the
+ * workflow's to stop (a machine-command row on the sender's role). An alarm
+ * row a person resolves acknowledges the alarm at the machine.
+ * A machine-command row is sent to its machine as the command it names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.concernsLine = concernsLine;
+exports.statusFits = statusFits;
+exports.planEscalationEvent = planEscalationEvent;
+const contracts_1 = require("../contracts");
+const commands_1 = require("../commands");
+const protocol_1 = require("../../../lib/machines/protocol");
+const line_1 = require("../../../lib/machines/line");
+const actions_1 = require("./actions");
+const plan_shared_1 = require("./plan-shared");
+const jobs_1 = require("./jobs");
+const pacing_1 = require("./pacing");
+const trace_1 = require("./trace");
+const state_1 = require("./state");
+const rows_1 = require("../rows");
+const registration_1 = require("./registration");
+const VERB = { CREATED: 'created', CLAIMED: 'claimed', RESOLVED: 'resolved', CANCELLED: 'cancelled', EXPIRED: 'expired' };
+/** The stored status a row must have for each verb the gateway acts on. */
+const STATUS_FOR_VERB = {
+    [VERB.CREATED]: 'pending', [VERB.CLAIMED]: 'pending', [VERB.RESOLVED]: 'resolved', [VERB.CANCELLED]: 'cancelled', [VERB.EXPIRED]: 'expired',
+};
+/** The metadata key an accumulator row parked with an item limit carries. */
+const ACCUMULATE_MAX = 'accumulate_max';
+const LINE_ROW_TYPES = [contracts_1.ROW_TYPE.ALARM, contracts_1.ROW_TYPE.MACHINE_OFFLINE, contracts_1.ROW_TYPE.MACHINE_QUIET, contracts_1.ROW_TYPE.MACHINE_COMMAND, contracts_1.ROW_TYPE.MACHINE_REGISTRATION];
+function handoffRow(id, role, facets, data) {
+    const metadata = data?.metadata;
+    const capped = metadata?.[ACCUMULATE_MAX] != null;
+    const createdAt = data?.created_at ? new Date(data.created_at).getTime() : NaN;
+    return {
+        ...facets, id, role, dispatch: state_1.DISPATCH_STATE.NONE, trace: (0, trace_1.readTrace)(metadata),
+        ...(capped ? { capped } : {}), ...(Number.isFinite(createdAt) ? { createdAt } : {}),
+    };
+}
+/** Rows for another line belong to that line's gateway. */
+function onThisLine(line, at) {
+    return at.siteId === line.siteId && at.lineId === line.lineId;
+}
+/** Whether an event names a row this line acts on; only then is the stored row read. */
+function concernsLine(state, line, event, rows = rows_1.standardRows) {
+    if (!STATUS_FOR_VERB[event.verb])
+        return false;
+    if (state.get(event.escalationId))
+        return true;
+    const facets = rows.toHandoff({ ...event.data, id: event.escalationId, role: event.role });
+    if (facets)
+        return onThisLine(line, facets);
+    return LINE_ROW_TYPES.includes(event.data?.type) && onThisLine(line, event.data?.metadata ?? {});
+}
+/** Whether a stored row's status agrees with the event's verb, so a stale or invented event does nothing. */
+function statusFits(verb, status) {
+    return STATUS_FOR_VERB[verb] === status;
+}
+/** A handoff into a machine is parked on that machine's role; one to a person, on one of the line's receiver roles. */
+function handoffRoleFits(line, facets, role) {
+    if (onLine(line, facets.toMachine))
+        return role === (0, line_1.machineRole)((0, line_1.machineById)(line, facets.toMachine));
+    return (0, line_1.receiverRoles)(line).includes(role);
+}
+function planEscalationEvent(state, line, event, dispatchTtlMs, rows = rows_1.standardRows) {
+    const view = { ...event.data, id: event.escalationId, role: event.role };
+    const facets = rows.toHandoff(view);
+    if (facets)
+        return onThisLine(line, facets) && handoffRoleFits(line, facets, event.role) ? planHandoff(state, line, event, facets, dispatchTtlMs) : [];
+    if (state.get(event.escalationId))
+        return planHandoff(state, line, event, null, dispatchTtlMs);
+    const type = event.data?.type;
+    if (!onThisLine(line, event.data?.metadata ?? {}))
+        return [];
+    if (type === contracts_1.ROW_TYPE.ALARM)
+        return planAlarmRow(state, event);
+    if (type === contracts_1.ROW_TYPE.MACHINE_OFFLINE || type === contracts_1.ROW_TYPE.MACHINE_QUIET)
+        return planLinkRow(state, event);
+    if (type === contracts_1.ROW_TYPE.MACHINE_COMMAND)
+        return planCommandRow(state, line, event);
+    if (type === contracts_1.ROW_TYPE.MACHINE_REGISTRATION)
+        return event.role === (0, line_1.operatorRole)(line) ? (0, registration_1.planRegistrationRow)(state, line, event) : [];
+    return [];
+}
+/** Why the gateway will not send a command row's command; null when it will. */
+function commandRefusal(state, line, c, role) {
+    if (!onLine(line, c.machineId))
+        return `${c.machineId} is not on ${line.siteId}/${line.lineId}`;
+    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(', ')}`;
+    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))
+        return `${c.machineId} has not registered an address yet`;
+    return null;
+}
+function planCommandRow(state, line, event) {
+    const id = event.escalationId;
+    if (event.verb === VERB.RESOLVED || event.verb === VERB.CANCELLED || event.verb === VERB.EXPIRED) {
+        state.endCommand(id);
+        return [];
+    }
+    if (event.verb !== VERB.CREATED && event.verb !== VERB.CLAIMED)
+        return [];
+    const c = (0, commands_1.readCommandFacets)(event.data?.metadata);
+    if (!c || !state.trackCommand(id))
+        return [];
+    const refusal = commandRefusal(state, line, c, event.role);
+    if (refusal) {
+        return [{ kind: 'resolve', as: actions_1.CONTROLLER, rowId: id, payload: { accepted: false, machineId: c.machineId, op: c.op, status: contracts_1.COMMAND_STATUS.UNSUPPORTED, reason: refusal } }];
+    }
+    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 } : {}) }];
+}
+function onLine(line, machineId) {
+    return !!machineId && line.machines.some((m) => m.machineId === machineId);
+}
+function heldUnder(state, machineId, unitId, senderJobId) {
+    const held = state.heldJob(machineId, unitId);
+    return !!held && (!senderJobId || (0, jobs_1.jobOwns)(senderJobId, held));
+}
+function planHandoff(state, line, event, facets, dispatchTtlMs) {
+    const id = event.escalationId;
+    if (event.verb === VERB.CREATED || event.verb === VERB.CLAIMED) {
+        if (state.isClosed(id) || !facets)
+            return [];
+        state.index(handoffRow(id, event.role, facets, event.data));
+        const row = state.get(id);
+        // The units now wait on the sender as this row's sender job, when the sender holds them under it.
+        if (row.fromMachine)
+            for (const u of row.units)
+                if (heldUnder(state, row.fromMachine, u.unitId, row.senderJobId))
+                    state.letGo(row.fromMachine, u.unitId);
+        if (!onLine(line, row.toMachine) || row.dispatch !== state_1.DISPATCH_STATE.NONE)
+            return [];
+        // Read back already claimed: the machine accepted it before this gateway started.
+        if (event.data?.assigned_to) {
+            row.dispatch = state_1.DISPATCH_STATE.ACCEPTED;
+            return [];
+        }
+        if (state.dispatchOnArrival) {
+            const refused = (0, pacing_1.refuseUnfit)(state, line, row);
+            if (!refused.length)
+                row.dispatch = state_1.DISPATCH_STATE.ARRIVING;
+            return refused;
+        }
+        const refused = !!(0, pacing_1.softwareRefusal)(state, line, row.toMachine) || !!(0, pacing_1.jobRefusal)(state, row);
+        if (state.holdDispatch || (!refused && (!(0, pacing_1.hasRoom)(state, line, row) || !(0, registration_1.reachable)(state, line, row.toMachine)))) {
+            row.dispatch = state_1.DISPATCH_STATE.WAITING;
+            return [];
+        }
+        return (0, pacing_1.admit)(state, line, row, dispatchTtlMs);
+    }
+    if (event.verb === VERB.CANCELLED || event.verb === VERB.EXPIRED) {
+        const row = state.close(id, event.verb === VERB.CANCELLED ? state_1.ROW_END.CANCELLED : state_1.ROW_END.EXPIRED);
+        return row ? (0, plan_shared_1.cancelDispatch)(state, row) : [];
+    }
+    if (event.verb === VERB.RESOLVED)
+        state.close(id);
+    return [];
+}
+function planAlarmRow(state, event) {
+    const md = event.data.metadata ?? {};
+    const track = state.alarms.get(state.alarmKey(md.machineId, md.alarmId));
+    if (event.verb === VERB.CREATED) {
+        // A row for an earlier raise of the same alarm id is not this raise's row.
+        if (track && !track.rowId && (!track.raisedAt || !md.raisedAt || track.raisedAt === md.raisedAt))
+            track.rowId = event.escalationId;
+        return [];
+    }
+    // Only the row of the raise still tracked speaks for it; an older row ending acknowledges nothing.
+    if (!track || track.rowId !== event.escalationId || (event.verb !== VERB.RESOLVED && event.verb !== VERB.CANCELLED))
+        return [];
+    track.open = false;
+    if (event.verb !== VERB.RESOLVED)
+        return [];
+    // Still tracked means the machine has not cleared it: a person acknowledged it.
+    return [{
+            kind: 'command', machineId: track.machineId, op: protocol_1.OP.ACKNOWLEDGE_ALARM, cmdId: `${event.escalationId}:ack`,
+            args: { alarmId: track.alarmId, by: event.data.resolved_by ?? 'line-operator' },
+        }];
+}
+function planLinkRow(state, event) {
+    const machineId = event.data.metadata?.machineId;
+    const link = machineId ? state.links.get(machineId) : undefined;
+    if (!link)
+        return [];
+    const quiet = event.data.type === contracts_1.ROW_TYPE.MACHINE_QUIET;
+    const ended = event.verb === VERB.RESOLVED || event.verb === VERB.CANCELLED;
+    if (quiet) {
+        if (event.verb === VERB.CREATED)
+            link.quietRowId = event.escalationId;
+        if (ended && link.quietRowId === event.escalationId)
+            link.quietRowId = undefined;
+    }
+    else {
+        if (event.verb === VERB.CREATED)
+            link.rowId = event.escalationId;
+        if (ended && link.rowId === event.escalationId)
+            link.rowId = undefined;
+    }
+    return [];
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 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. A job's
+ * start, its progress steps, and the alarms that pause it are noted on the row
+ * that holds it (lifecycle.ts). 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.
+ */
+import { type Envelope, type ParsedTopic } from '../../../lib/machines/protocol';
+import { type Plan } from './actions';
+import { type GatewayState } from './state';
+export declare function planMachineMessage(state: GatewayState, parsed: ParsedTopic, env: Envelope | null, dispatchTtlMs: number): Plan;

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

@@ -0,0 +1,283 @@
+"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. A job's
+ * start, its progress steps, and the alarms that pause it are noted on the row
+ * that holds it (lifecycle.ts). 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 lifecycle_1 = require("./lifecycle");
+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, at) {
+    row.arrivals = { ...row.arrivals, [unitId]: b };
+    row.dueAt = (0, pacing_1.latestArrival)(row.dueAt, at);
+    return row;
+}
+/** The unit an open handoff into `m` carries on `carrierId`, for a scan that read only the carrier. */
+function unitOnCarrier(state, m, carrierId) {
+    if (typeof carrierId !== 'string')
+        return undefined;
+    for (const r of state.open()) {
+        if (r.toMachine !== m)
+            continue;
+        const unit = r.units.find((u) => u.carrierId === carrierId);
+        if (unit)
+            return unit.unitId;
+    }
+    return undefined;
+}
+function planJob(state, m, b, at, ttl) {
+    const unitId = typeof b.unitId === 'string' ? b.unitId : unitOnCarrier(state, m, b.carrierId);
+    // A carrier no open handoff here carries yet: its row may still be on the way.
+    if (unitId === undefined)
+        return nak;
+    // 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 arrivedAt = at ?? new Date().toISOString();
+        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, arrivedAt), 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: arrivedAt,
+                    ...(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}` }));
+    }
+    if (b.event === protocol_1.JOB_EVENT.STARTED || b.event === protocol_1.JOB_EVENT.PROGRESS)
+        return ack((0, lifecycle_1.noteJobEvent)(state, m, b, at));
+    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);
+        const resumed = track ? (0, lifecycle_1.noteResume)(state, track, b) : [];
+        if (!track?.rowId || !track.open)
+            return ack(resumed);
+        return ack([...resumed, {
+                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` } }]
+        : [];
+    const track = { machineId: m, alarmId, raisedAt: b.raisedAt, open: true };
+    state.alarms.set(key, track);
+    return ack([...superseded, ...(0, lifecycle_1.notePause)(state, track, b), {
+            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 fresh = !state.retainedAlarms && !state.readingRetained && Array.isArray(b.alarms);
+    const cleared = fresh ? alarmsNoLongerListed(state, m, b.alarms) : [];
+    const answer = { kind: 'settleSnapshot', machineId: m, jobIds };
+    const previous = link.bootId;
+    link.bootId = b.bootId;
+    if (!previous || previous === b.bootId)
+        return ack([...cleared, 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([...cleared, answer, ...lost.map((r) => (0, pacing_1.dispatchAction)(r, m, ttl))]);
+}
+/** Alarm rows for `m` whose alarm its snapshot no longer lists: they cleared at the machine. */
+function alarmsNoLongerListed(state, m, listed) {
+    const active = new Set(listed.filter((id) => typeof id === 'string'));
+    const actions = [];
+    for (const [key, track] of [...state.alarms.entries()]) {
+        if (track.machineId !== m || active.has(track.alarmId))
+            continue;
+        state.alarms.delete(key);
+        actions.push(...(0, lifecycle_1.noteResume)(state, track, {}));
+        if (track.open && track.rowId) {
+            actions.push({ kind: 'resolve', as: actions_1.CONTROLLER, rowId: track.rowId, payload: { decision: contracts_1.DECISION.CLEARED, note: `cleared at ${m}; its snapshot no longer lists it` } });
+        }
+    }
+    return actions;
+}

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>>;