@hotmeshio/long-tail 0.25.4 → 0.27.0

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

@@ -0,0 +1,21 @@
+/**
+ * Job lifecycle on the row. A machine's started and progress events, and the
+ * alarms that stop it, are noted as items on the open row that holds the job:
+ * the accepted dispatch into the machine until its units arrive, then the
+ * handoff out of it. Progress is noted only when it crosses a step, or reaches
+ * a named stage it has not reached before, so a row carries a handful of items
+ * while the stream keeps every report.
+ *
+ * Off unless the line turns it on (MACHINE_LIFECYCLE=on). A row parked with a
+ * limit on its items gets no notes, so they never use a slot its units need.
+ */
+import type { Action } from './actions';
+import { type AlarmTrack, type GatewayState } from './state';
+/** The progress step `percent` has reached; null below the first step, at 100, or when steps are off. */
+export declare function progressStepOf(percent: unknown, step: number): number | null;
+/** A started or progress event, noted on the row that holds the job. */
+export declare function noteJobEvent(state: GatewayState, m: string, b: Record<string, any>, at: string | undefined): Action[];
+/** Rows a stopping alarm pauses: those running or leaving with its job, or every row the machine holds. */
+export declare function notePause(state: GatewayState, track: AlarmTrack, b: Record<string, any>): Action[];
+/** The machine cleared an alarm: the rows it paused, still open, note the resume. */
+export declare function noteResume(state: GatewayState, track: AlarmTrack, b: Record<string, any>): Action[];

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

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Job lifecycle on the row. A machine's started and progress events, and the
+ * alarms that stop it, are noted as items on the open row that holds the job:
+ * the accepted dispatch into the machine until its units arrive, then the
+ * handoff out of it. Progress is noted only when it crosses a step, or reaches
+ * a named stage it has not reached before, so a row carries a handful of items
+ * while the stream keeps every report.
+ *
+ * Off unless the line turns it on (MACHINE_LIFECYCLE=on). A row parked with a
+ * limit on its items gets no notes, so they never use a slot its units need.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.progressStepOf = progressStepOf;
+exports.noteJobEvent = noteJobEvent;
+exports.notePause = notePause;
+exports.noteResume = noteResume;
+const contracts_1 = require("../contracts");
+const protocol_1 = require("../../../lib/machines/protocol");
+const jobs_1 = require("./jobs");
+const state_1 = require("./state");
+const owns = (jobId, reported) => !jobId || typeof reported !== 'string' || (0, jobs_1.jobOwns)(jobId, reported);
+const runningAt = (r, m, jobId) => r.toMachine === m && r.dispatch === state_1.DISPATCH_STATE.ACCEPTED && owns(r.jobId, jobId);
+const leavingFrom = (r, m, jobId) => r.fromMachine === m && !!r.senderJobId && owns(r.senderJobId, jobId);
+/** The open row holding `unitId` at `m`: its accepted dispatch, else the handoff out of `m`. */
+function holderRow(state, m, unitId, jobId) {
+    return state.openFor(unitId, (r) => runningAt(r, m, jobId)) ?? state.openFor(unitId, (r) => leavingFrom(r, m, jobId));
+}
+/** The progress step `percent` has reached; null below the first step, at 100, or when steps are off. */
+function progressStepOf(percent, step) {
+    if (step <= 0 || typeof percent !== 'number' || !Number.isFinite(percent))
+        return null;
+    const reached = Math.floor(percent / step) * step;
+    return reached > 0 && reached < 100 ? reached : null;
+}
+/** An item the row does not hold yet, added as the machine. */
+function note(row, m, itemKey, payload, metadata) {
+    if (row.capped || row.noted?.includes(itemKey))
+        return [];
+    row.noted = [...(row.noted ?? []), itemKey];
+    return [{ kind: 'accumulate', as: m, rowId: row.id, itemKey, payload, ...(metadata ? { metadata } : {}) }];
+}
+/** A started or progress event, noted on the row that holds the job. */
+function noteJobEvent(state, m, b, at) {
+    const unitId = b.unitId;
+    if (!state.lifecycle || typeof unitId !== 'string')
+        return [];
+    const row = holderRow(state, m, unitId, b.jobId);
+    if (!row)
+        return [];
+    const when = at ?? new Date().toISOString();
+    if (b.event === protocol_1.JOB_EVENT.STARTED) {
+        return note(row, m, contracts_1.itemKeys.started(unitId), { unitId, jobId: b.jobId ?? null, at: when });
+    }
+    const step = progressStepOf(b.percent, state.progressStep);
+    const stage = typeof b.stage === 'string' && b.stage ? b.stage : null;
+    if (step === null && stage === null)
+        return [];
+    const progress = {
+        ...(typeof b.percent === 'number' ? { percent: b.percent } : {}), remainingSec: b.remainingSec ?? null, ...(stage ? { stage } : {}), at: when,
+        ...(b.detail && typeof b.detail === 'object' ? { detail: b.detail } : {}),
+    };
+    const facet = { [contracts_1.LIFECYCLE_FACET.PROGRESS]: progress };
+    const job = { unitId, jobId: b.jobId ?? null };
+    return [
+        ...(step === null ? [] : note(row, m, contracts_1.itemKeys.progress(unitId, step), { ...job, step, ...progress }, facet)),
+        ...(stage === null ? [] : note(row, m, contracts_1.itemKeys.stage(unitId, stage), { ...job, ...progress }, facet)),
+    ];
+}
+/** Rows a stopping alarm pauses: those running or leaving with its job, or every row the machine holds. */
+function notePause(state, track, b) {
+    if (!state.lifecycle)
+        return [];
+    const m = track.machineId;
+    const jobId = typeof b.jobId === 'string' ? b.jobId : undefined;
+    const rows = state.open().filter((r) => runningAt(r, m, jobId) || leavingFrom(r, m, jobId));
+    track.noted = rows.map((r) => r.id);
+    const payload = { alarmId: track.alarmId, code: b.code ?? null, level: b.level ?? null, text: b.text ?? null, raisedAt: b.raisedAt ?? null };
+    return rows.flatMap((r) => note(r, m, contracts_1.itemKeys.paused(track.alarmId, String(b.raisedAt ?? '')), payload));
+}
+/** The machine cleared an alarm: the rows it paused, still open, note the resume. */
+function noteResume(state, track, b) {
+    const key = contracts_1.itemKeys.resumed(track.alarmId, String(track.raisedAt ?? ''));
+    const payload = { alarmId: track.alarmId, clearedAt: b.clearedAt ?? new Date().toISOString(), clearedBy: b.clearedBy ?? null };
+    return (track.noted ?? [])
+        .map((id) => state.get(id))
+        .filter((r) => !!r && !r.ended)
+        .flatMap((r) => note(r, track.machineId, key, payload));
+}

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

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

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,43 @@
+/**
+ * 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>;
+/**
+ * The validity round a dispatch belongs to. Rounds of one validity period count
+ * from when the dispatch became due, and a round begins only when the one
+ * before it has expired, so a machine never holds two valid commands for one
+ * row. Within a round a dispatch sent again, by a retry, a restarted machine or
+ * a restarted gateway, is the same command with the same arguments; a new round
+ * is a new command, never an old one with changed arguments.
+ */
+export declare function dispatchWindow(dueAt: number, now: number, ttlMs: number): {
+    round: number;
+    expiresAt: number;
+};
+/** The later of a row's due time and an arrival's time; an unreadable time leaves it as it was. */
+export declare function latestArrival(dueAt: number | undefined, at: unknown): number | undefined;
+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,158 @@
+"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.dispatchWindow = dispatchWindow;
+exports.latestArrival = latestArrival;
+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 } : {}),
+    };
+}
+/**
+ * The validity round a dispatch belongs to. Rounds of one validity period count
+ * from when the dispatch became due, and a round begins only when the one
+ * before it has expired, so a machine never holds two valid commands for one
+ * row. Within a round a dispatch sent again, by a retry, a restarted machine or
+ * a restarted gateway, is the same command with the same arguments; a new round
+ * is a new command, never an old one with changed arguments.
+ */
+function dispatchWindow(dueAt, now, ttlMs) {
+    const round = Math.max(1, Math.floor((now - dueAt) / ttlMs) + 1);
+    return { round, expiresAt: dueAt + round * ttlMs };
+}
+/** The later of a row's due time and an arrival's time; an unreadable time leaves it as it was. */
+function latestArrival(dueAt, at) {
+    const t = typeof at === 'string' ? Date.parse(at) : NaN;
+    if (!Number.isFinite(t))
+        return dueAt;
+    return dueAt === undefined ? t : Math.max(dueAt, t);
+}
+function dispatchAction(row, machineId, dispatchTtlMs) {
+    const now = Date.now();
+    row.createdAt ??= now;
+    const { round, expiresAt } = dispatchWindow(row.dueAt ?? row.createdAt, now, dispatchTtlMs);
+    return {
+        kind: 'dispatch', rowId: row.id, machineId, cmdId: (0, contracts_1.dispatchCommandId)(row.id, round), args: dispatchArgs(row, expiresAt),
+        ...(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 || u.artifacts?.length))
+        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[];