@hotmeshio/long-tail 0.25.3 → 0.26.0

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silentLog = exports.consoleLog = exports.GATEWAY_LOG = void 0;
+exports.GATEWAY_LOG = {
+    STARTED: 'machine_gateway.started',
+    RECONCILED: 'machine_gateway.reconciled',
+    DISPATCHED: 'machine_gateway.dispatch.accepted',
+    DISPATCH_REFUSED: 'machine_gateway.dispatch.refused',
+    DISPATCH_READY: 'machine_gateway.dispatch.ready',
+    DISPATCH_FAILED: 'machine_gateway.dispatch.failed',
+    DISPATCH_RECONCILED: 'machine_gateway.dispatch.reconciled',
+    VERB_INVALID: 'machine_gateway.verb.invalid',
+    VERB_FAILED: 'machine_gateway.verb.failed',
+    ROW_NOT_VISIBLE: 'machine_gateway.verb.row_not_visible',
+    ROW_CLAIMED_ELSEWHERE: 'machine_gateway.verb.row_claimed_elsewhere',
+    UNMATCHED: 'machine_gateway.message.unmatched',
+    UNREADABLE: 'machine_gateway.message.unreadable',
+    CONTRACT_VIOLATION: 'machine_gateway.contract.violation',
+    VIOLATION_ROW: 'machine_gateway.contract.row_created',
+    ADDRESS_BOUND: 'machine_gateway.address.bound',
+    ADDRESS_CONTESTED: 'machine_gateway.address.contested',
+    ADDRESS_UNKNOWN: 'machine_gateway.address.unknown',
+    ADDRESS_REFUSED: 'machine_gateway.address.refused',
+    RECEIPT_FAILED: 'machine_gateway.receipt.failed',
+    ALARM_ROW: 'machine_gateway.alarm.row_created',
+    OFFLINE_ROW: 'machine_gateway.offline.row_created',
+    QUIET_ROW: 'machine_gateway.quiet.row_created',
+    COMMANDED: 'machine_gateway.command.accepted',
+    COMMAND_REFUSED: 'machine_gateway.command.refused',
+    COMMAND_UNANSWERED: 'machine_gateway.command.unanswered',
+    COMMAND_UNSUPPORTED: 'machine_gateway.command.unsupported',
+    LEADING: 'machine_gateway.line.leading',
+    STANDBY: 'machine_gateway.line.standby',
+    LEADERSHIP_LOST: 'machine_gateway.line.leadership_lost',
+    START_FAILED: 'machine_gateway.line.start_failed',
+};
+exports.consoleLog = {
+    info: (event, context) => console.log(JSON.stringify({ level: 'info', event, ...context })),
+    warn: (event, context) => console.warn(JSON.stringify({ level: 'warn', event, ...context })),
+    error: (event, context) => console.error(JSON.stringify({ level: 'error', event, ...context })),
+};
+exports.silentLog = { info: () => undefined, warn: () => undefined, error: () => undefined };

package/build/services/machines/gateway/lt-http.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The gateway's HTTP client to Long Tail. A non-2xx response throws
+ * LtHttpError with the status, body and request; the escalation verbs turn
+ * the outcomes that mean "already done" (404, 409) and "invalid" (422) into
+ * VerbResults and let every other failure throw, so the message that caused
+ * it is delivered again.
+ */
+import type { OpenRowQuery } from '../rows';
+import { type Actor, type CreateRowInput } from './actions';
+import { type LineEscalations, type RowItem, type VerbResult } from './escalations';
+export declare class LtHttpError extends Error {
+    readonly status: number | undefined;
+    readonly body: unknown;
+    readonly context: {
+        method: string;
+        path: string;
+        elapsedMs: number;
+    };
+    readonly cause?: unknown;
+    constructor(message: string, status: number | undefined, body: unknown, context: {
+        method: string;
+        path: string;
+        elapsedMs: number;
+    }, options?: {
+        cause?: unknown;
+    });
+}
+export declare class LtHttp {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(baseUrl: string, timeoutMs?: number);
+    request<T = any>(method: string, path: string, token: string | null, body?: unknown): Promise<T>;
+}
+/** Escalation verbs over HTTP, each run with the bearer token of the actor it runs as. */
+export declare class HttpLineEscalations implements LineEscalations {
+    private readonly http;
+    private readonly tokenFor;
+    private readonly claimMinutes;
+    constructor(http: LtHttp, tokenFor: (as: Actor) => string, claimMinutes?: number);
+    claim(as: Actor, id: string): Promise<VerbResult>;
+    accumulate(as: Actor, id: string, itemKey: string, payload: Record<string, any>, metadata?: Record<string, any>): Promise<VerbResult>;
+    resolve(as: Actor, id: string, payload: Record<string, any>): Promise<VerbResult>;
+    create(as: Actor, input: CreateRowInput): Promise<{
+        id: string;
+    }>;
+    itemKeys(id: string): Promise<string[]>;
+    items(id: string): Promise<RowItem[]>;
+    get(id: string): Promise<Record<string, any> | null>;
+    listOpen(filter: OpenRowQuery): Promise<Record<string, any>[]>;
+    private verb;
+}

package/build/services/machines/gateway/lt-http.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * The gateway's HTTP client to Long Tail. A non-2xx response throws
+ * LtHttpError with the status, body and request; the escalation verbs turn
+ * the outcomes that mean "already done" (404, 409) and "invalid" (422) into
+ * VerbResults and let every other failure throw, so the message that caused
+ * it is delivered again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpLineEscalations = exports.LtHttp = exports.LtHttpError = void 0;
+const uuid_1 = require("../../../lib/uuid");
+const actions_1 = require("./actions");
+const escalations_1 = require("./escalations");
+class LtHttpError extends Error {
+    constructor(message, status, body, context, options) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.context = context;
+        this.name = 'LtHttpError';
+        this.cause = options?.cause;
+    }
+}
+exports.LtHttpError = LtHttpError;
+class LtHttp {
+    constructor(baseUrl, timeoutMs = 10_000) {
+        this.baseUrl = baseUrl;
+        this.timeoutMs = timeoutMs;
+    }
+    async request(method, path, token, body) {
+        const started = performance.now();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const context = () => ({ method, path, elapsedMs: Math.round(performance.now() - started) });
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}/api${path}`, {
+                method,
+                headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const reason = controller.signal.aborted ? `timed out after ${this.timeoutMs} ms` : err.message;
+            throw new LtHttpError(`${method} ${path}: ${reason}`, undefined, undefined, context(), { cause: err });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        const parsed = (res.headers.get('content-type') ?? '').includes('json') && text ? JSON.parse(text) : text;
+        if (!res.ok)
+            throw new LtHttpError(`${method} ${path} → ${res.status}`, res.status, parsed, context());
+        return parsed;
+    }
+}
+exports.LtHttp = LtHttp;
+/** Escalation verbs over HTTP, each run with the bearer token of the actor it runs as. */
+class HttpLineEscalations {
+    constructor(http, tokenFor, claimMinutes = 24 * 60) {
+        this.http = http;
+        this.tokenFor = tokenFor;
+        this.claimMinutes = claimMinutes;
+    }
+    claim(as, id) {
+        return this.verb(as, 'POST', `/escalations/${id}/claim`, { durationMinutes: this.claimMinutes });
+    }
+    accumulate(as, id, itemKey, payload, metadata) {
+        return this.verb(as, 'POST', `/escalations/${id}/accumulate`, { itemKey, payload, ...(metadata ? { metadata } : {}) });
+    }
+    resolve(as, id, payload) {
+        return this.verb(as, 'POST', `/escalations/${id}/resolve`, { resolverPayload: payload });
+    }
+    async create(as, input) {
+        const row = await this.http.request('POST', '/escalations', this.tokenFor(as), input);
+        return { id: row.id };
+    }
+    async itemKeys(id) {
+        return (await this.items(id)).map((i) => i.itemKey);
+    }
+    async items(id) {
+        const view = await this.http.request('GET', `/escalations/${id}/items`, this.tokenFor(actions_1.CONTROLLER));
+        return view.items.map((i) => ({ itemKey: i.itemKey, payload: i.payload ?? {} }));
+    }
+    async get(id) {
+        if (!(0, uuid_1.isUuid)(id))
+            return null;
+        try {
+            return await this.http.request('GET', `/escalations/${encodeURIComponent(id)}`, this.tokenFor(actions_1.CONTROLLER));
+        }
+        catch (err) {
+            if (err instanceof LtHttpError && (err.status === 403 || err.status === 404))
+                return null;
+            throw err;
+        }
+    }
+    async listOpen(filter) {
+        return (0, escalations_1.readAllPages)(async (offset) => {
+            const query = new URLSearchParams({
+                ...filter, status: 'pending', limit: String(escalations_1.OPEN_PAGE), offset: String(offset), sort_by: 'created_at', order: 'asc',
+            });
+            const page = await this.http.request('GET', `/escalations?${query}`, this.tokenFor(actions_1.CONTROLLER));
+            return page.escalations;
+        });
+    }
+    async verb(as, method, path, body) {
+        try {
+            await this.http.request(method, path, this.tokenFor(as), body);
+            return { outcome: escalations_1.VERB_OUTCOME.DONE };
+        }
+        catch (err) {
+            const outcome = err instanceof LtHttpError && err.status !== undefined ? (0, escalations_1.verbOutcomeOf)(err.status) : null;
+            if (!outcome)
+                throw err;
+            return { outcome, detail: JSON.stringify(err.body), status: err.status };
+        }
+    }
+}
+exports.HttpLineEscalations = HttpLineEscalations;

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

@@ -0,0 +1,29 @@
+/**
+ * Pacing: a machine with a queue depth is sent no more jobs than that at once.
+ * A handoff beyond it waits in the machine's role queue, unclaimed, the way
+ * work waits for a busy person, and the oldest waiting row goes out when the
+ * machine has room. A machine's load is every job it has been sent or still
+ * holds: rows dispatched into it, rows whose units wait on it to move on, and
+ * units that arrived and have not left yet.
+ */
+import { type LineDef } from '../../../lib/machines/line';
+import { type Action } from './actions';
+import { type GatewayState, type HandoffRow } from './state';
+/** Dispatch arguments for a handoff row. */
+export declare function dispatchArgs(row: HandoffRow, expiresAt: number): Record<string, any>;
+export declare function dispatchAction(row: HandoffRow, machineId: string, dispatchTtlMs: number): Action;
+/** A machine on a version the line does not allow is refused before any dispatch. */
+export declare function softwareRefusal(state: GatewayState, line: LineDef, machineId: string): string | null;
+/** A machine that requires an artifact is never sent a handoff without one: the job's, or one for every unit. */
+export declare function artifactRefusal(line: LineDef, row: HandoffRow): string | null;
+/** The jobs `machineId` has been sent or still holds. */
+export declare function machineLoad(state: GatewayState, machineId: string): Set<string>;
+export declare function hasRoom(state: GatewayState, line: LineDef, row: HandoffRow): boolean;
+/** Two open handoffs may not name the same job at one machine: each row, subsets of a route's units included, needs its own. */
+export declare function jobRefusal(state: GatewayState, row: HandoffRow): string | null;
+/** The resolution refusing a handoff for the machine's software, a missing artifact or a job id in use; empty when it may go. */
+export declare function refuseUnfit(state: GatewayState, line: LineDef, row: HandoffRow): Action[];
+/** Send a handoff to its machine now, or refuse it for the machine's software or a missing artifact. */
+export declare function admit(state: GatewayState, line: LineDef, row: HandoffRow, dispatchTtlMs: number): Action[];
+/** Dispatch waiting rows, oldest first, while their machines have room; a full machine holds back its later rows too. */
+export declare function planPacing(state: GatewayState, line: LineDef, dispatchTtlMs: number): Action[];

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

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Pacing: a machine with a queue depth is sent no more jobs than that at once.
+ * A handoff beyond it waits in the machine's role queue, unclaimed, the way
+ * work waits for a busy person, and the oldest waiting row goes out when the
+ * machine has room. A machine's load is every job it has been sent or still
+ * holds: rows dispatched into it, rows whose units wait on it to move on, and
+ * units that arrived and have not left yet.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchArgs = dispatchArgs;
+exports.dispatchAction = dispatchAction;
+exports.softwareRefusal = softwareRefusal;
+exports.artifactRefusal = artifactRefusal;
+exports.machineLoad = machineLoad;
+exports.hasRoom = hasRoom;
+exports.jobRefusal = jobRefusal;
+exports.refuseUnfit = refuseUnfit;
+exports.admit = admit;
+exports.planPacing = planPacing;
+const contracts_1 = require("../contracts");
+const protocol_1 = require("../../../lib/machines/protocol");
+const line_1 = require("../../../lib/machines/line");
+const actions_1 = require("./actions");
+const jobs_1 = require("./jobs");
+const state_1 = require("./state");
+const registration_1 = require("./registration");
+/** Dispatch arguments for a handoff row. */
+function dispatchArgs(row, expiresAt) {
+    return {
+        jobId: row.jobId,
+        orderRef: row.orderRef,
+        recipe: { id: row.recipeId, version: row.recipeVersion },
+        units: row.arrivals ? row.units.map((u) => ({ ...u, arrival: row.arrivals?.[u.unitId] ?? null })) : row.units,
+        process: row.process,
+        from: row.fromMachine,
+        expiresAt: (0, protocol_1.isoTs)(expiresAt),
+        ...(row.artifactUrl ? { artifact: { url: row.artifactUrl, sha256: row.artifactSha256 } } : {}),
+        ...(row.parameters ? { parameters: row.parameters } : {}),
+    };
+}
+function dispatchAction(row, machineId, dispatchTtlMs) {
+    return {
+        kind: 'dispatch', rowId: row.id, machineId, cmdId: (0, contracts_1.dispatchCommandId)(row.id), args: dispatchArgs(row, Date.now() + dispatchTtlMs),
+        ...(row.dispatch === state_1.DISPATCH_STATE.ARRIVING ? { receivedOnAccept: true } : {}),
+    };
+}
+/** A machine on a version the line does not allow is refused before any dispatch. */
+function softwareRefusal(state, line, machineId) {
+    const allowed = (0, line_1.machineById)(line, machineId).allowedSoftware;
+    const software = state.links.get(machineId)?.software;
+    if (!allowed || !software || allowed.includes(software))
+        return null;
+    return `${machineId} runs ${software}; allowed: ${allowed.join(', ')}`;
+}
+/** A machine that requires an artifact is never sent a handoff without one: the job's, or one for every unit. */
+function artifactRefusal(line, row) {
+    if (!(0, line_1.machineById)(line, row.toMachine).requireArtifact || (row.artifactUrl && row.artifactSha256))
+        return null;
+    if (row.units.every((u) => u.artifact))
+        return null;
+    return `${row.toMachine} requires an artifact (url and sha256), for the job or for every unit; the row has none`;
+}
+const SENT = [state_1.DISPATCH_STATE.PENDING, state_1.DISPATCH_STATE.ACCEPTED];
+const jobIdsOf = (state, jobId, row) => (0, jobs_1.dispatchJobs)(jobId, row.units, state.unitsPerDispatch).map((j) => j.jobId);
+/** The jobs `machineId` has been sent or still holds. */
+function machineLoad(state, machineId) {
+    const jobs = new Set(state.heldAt(machineId));
+    for (const r of state.open()) {
+        if (r.toMachine === machineId && SENT.includes(r.dispatch))
+            for (const id of jobIdsOf(state, r.jobId, r))
+                jobs.add(id);
+        if (r.fromMachine === machineId && r.senderJobId)
+            for (const id of jobIdsOf(state, r.senderJobId, r))
+                jobs.add(id);
+    }
+    return jobs;
+}
+/** Whether a row's jobs fit at its receiver; an idle machine always takes the next row, however large. */
+function fits(line, row, load, state) {
+    const depth = (0, line_1.machineById)(line, row.toMachine).queueDepth;
+    return !depth || load.size === 0 || load.size + jobIdsOf(state, row.jobId, row).length <= depth;
+}
+function hasRoom(state, line, row) {
+    return fits(line, row, machineLoad(state, row.toMachine), state);
+}
+/** Two open handoffs may not name the same job at one machine: each row, subsets of a route's units included, needs its own. */
+function jobRefusal(state, row) {
+    const other = state.open().find((r) => r.id !== row.id && r.toMachine === row.toMachine && r.jobId === row.jobId && r.dispatch !== state_1.DISPATCH_STATE.REFUSED);
+    return other ? `job ${row.jobId} at ${row.toMachine} already belongs to handoff ${other.id}` : null;
+}
+/** The resolution refusing a handoff for the machine's software, a missing artifact or a job id in use; empty when it may go. */
+function refuseUnfit(state, line, row) {
+    const software = softwareRefusal(state, line, row.toMachine);
+    const other = software ?? artifactRefusal(line, row) ?? jobRefusal(state, row);
+    if (!other)
+        return [];
+    row.dispatch = state_1.DISPATCH_STATE.REFUSED;
+    const errorCode = software ? contracts_1.HANDOFF_ERROR.SOFTWARE_UNSUPPORTED : contracts_1.HANDOFF_ERROR.DISPATCH_REFUSED;
+    return [{ kind: 'resolve', as: actions_1.CONTROLLER, rowId: row.id, payload: { received: false, errorCode, detail: other } }];
+}
+/** Send a handoff to its machine now, or refuse it for the machine's software or a missing artifact. */
+function admit(state, line, row, dispatchTtlMs) {
+    const refused = refuseUnfit(state, line, row);
+    if (refused.length)
+        return refused;
+    row.dispatch = state_1.DISPATCH_STATE.PENDING;
+    return [dispatchAction(row, row.toMachine, dispatchTtlMs)];
+}
+/** Dispatch waiting rows, oldest first, while their machines have room; a full machine holds back its later rows too. */
+function planPacing(state, line, dispatchTtlMs) {
+    const actions = [];
+    const loads = new Map();
+    const full = new Set();
+    for (const row of state.open()) {
+        const m = row.toMachine;
+        // A station that has not registered its address yet keeps its rows waiting.
+        if (row.dispatch !== state_1.DISPATCH_STATE.WAITING || !m || full.has(m) || !(0, registration_1.reachable)(state, line, m))
+            continue;
+        if (!loads.has(m))
+            loads.set(m, machineLoad(state, m));
+        const load = loads.get(m);
+        if (!fits(line, row, load, state)) {
+            full.add(m);
+            continue;
+        }
+        const admitted = admit(state, line, row, dispatchTtlMs);
+        actions.push(...admitted);
+        if (admitted.some((a) => a.kind === 'dispatch'))
+            for (const id of jobIdsOf(state, row.jobId, row))
+                load.add(id);
+    }
+    return actions;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+import { type LineDef } from '../../../lib/machines/line';
+import type { EscalationEvent } from '../../../lib/machines/transport';
+import { type Action } from './actions';
+import { type GatewayState } from './state';
+import { type HandoffRowAdapter } from '../rows';
+/** Whether an event names a row this line acts on; only then is the stored row read. */
+export declare function concernsLine(state: GatewayState, line: LineDef, event: EscalationEvent, rows?: HandoffRowAdapter): boolean;
+/** Whether a stored row's status agrees with the event's verb, so a stale or invented event does nothing. */
+export declare function statusFits(verb: string, status: unknown): boolean;
+export declare function planEscalationEvent(state: GatewayState, line: LineDef, event: EscalationEvent, dispatchTtlMs: number, rows?: HandoffRowAdapter): Action[];

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

@@ -0,0 +1,201 @@
+"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',
+};
+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, metadata) {
+    return { ...facets, id, role, dispatch: state_1.DISPATCH_STATE.NONE, trace: (0, trace_1.readTrace)(metadata) };
+}
+/** 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 } }];
+    }
+    return [{ kind: 'control', rowId: id, machineId: c.machineId, op: c.op, cmdId: (0, contracts_1.controlCommandId)(id), args: c.args }];
+}
+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?.metadata));
+        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,16 @@
+/**
+ * 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.
+ */
+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;