@hotmeshio/long-tail 0.27.0 → 0.28.1

package/build/services/knowledge/lookup-refs.js

@@ -21,7 +21,7 @@ async function describeMissingLookupRefs(refs) {
         const where = versions.length
             ? `editions: ${versions.map((v) => `v${v}`).join(', ')}`
             : `no knowledge entry ${ref.domain}/${ref.key}`;
-        const named = (0, escalation_1.isCurrentLookupRef)(ref) ? 'current' : `v${ref.version}`;
+        const named = (0, escalation_1.isCurrentLookupRef)(ref) ? 'current' : (0, escalation_1.isLabelLookupRef)(ref) ? `label ${JSON.stringify(ref.version)}` : `v${ref.version}`;
         problems.push(`Lookup ref ${ref.domain}/${ref.key} ${named} names no edition (${where})`);
     }
     return problems;

package/build/services/knowledge/sql.d.ts

@@ -1,4 +1,6 @@
-export declare const GET_KNOWLEDGE_VERSION = "\n  SELECT domain, key, version, data, tags, change_summary, created_at\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2 AND version = $3";
-export declare const LIST_KNOWLEDGE_VERSIONS = "\n  SELECT v.version, v.change_summary, v.created_at,\n         (v.version = k.current_version) AS is_current\n  FROM lt_knowledge_versions v\n  JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key\n  WHERE v.domain = $1 AND v.key = $2\n  ORDER BY v.version DESC";
+export declare const GET_KNOWLEDGE_VERSION = "\n  SELECT domain, key, version, label, data, tags, change_summary, created_at\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2 AND version = $3";
+/** The edition a label names, when one does. */
+export declare const GET_KNOWLEDGE_VERSION_BY_LABEL = "\n  SELECT version\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2 AND label = $3";
+export declare const LIST_KNOWLEDGE_VERSIONS = "\n  SELECT v.version, v.label, v.change_summary, v.created_at,\n         (v.version = k.current_version) AS is_current\n  FROM lt_knowledge_versions v\n  JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key\n  WHERE v.domain = $1 AND v.key = $2\n  ORDER BY v.version DESC";
 /** The newest edition, or the newest created at or before $3 when it is set. */
 export declare const GET_LATEST_KNOWLEDGE_VERSION = "\n  SELECT version, data, tags\n  FROM lt_knowledge_versions\n  WHERE domain = $1 AND key = $2\n    AND ($3::timestamptz IS NULL OR created_at <= $3)\n  ORDER BY version DESC\n  LIMIT 1";

package/build/services/knowledge/sql.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GET_LATEST_KNOWLEDGE_VERSION = exports.LIST_KNOWLEDGE_VERSIONS = exports.GET_KNOWLEDGE_VERSION = void 0;
+exports.GET_LATEST_KNOWLEDGE_VERSION = exports.LIST_KNOWLEDGE_VERSIONS = exports.GET_KNOWLEDGE_VERSION_BY_LABEL = exports.GET_KNOWLEDGE_VERSION = void 0;
 exports.GET_KNOWLEDGE_VERSION = `
-  SELECT domain, key, version, data, tags, change_summary, created_at
+  SELECT domain, key, version, label, data, tags, change_summary, created_at
   FROM lt_knowledge_versions
   WHERE domain = $1 AND key = $2 AND version = $3`;
+/** The edition a label names, when one does. */
+exports.GET_KNOWLEDGE_VERSION_BY_LABEL = `
+  SELECT version
+  FROM lt_knowledge_versions
+  WHERE domain = $1 AND key = $2 AND label = $3`;
 exports.LIST_KNOWLEDGE_VERSIONS = `
-  SELECT v.version, v.change_summary, v.created_at,
+  SELECT v.version, v.label, v.change_summary, v.created_at,
          (v.version = k.current_version) AS is_current
   FROM lt_knowledge_versions v
   JOIN lt_knowledge k ON k.domain = v.domain AND k.key = v.key

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

@@ -1,11 +1,11 @@
 /**
  * Commands as rows. A host asks a machine to start, stop, pause, resume,
- * change over or cancel a job by parking a machine-command row on the machine's role, from a
- * workflow step or through the API, the same way it asks a person for
+ * change over, cancel a job, report a snapshot, or do anything its codec
+ * declares (`rowOps`), by parking a machine-command row on the machine's role,
+ * from a workflow step or through the API, the same way it asks a person for
  * anything. The gateway sends the command and resolves the row with the
  * machine's reply (CommandResolution), so the step reads the outcome as data.
  */
-import type { Op } from '../../lib/machines/protocol';
 import { type LineDef } from '../../lib/machines/line';
 import { type CommandFacets } from './contracts';
 /** Where a command goes: the machine and the role its rows land on. */
@@ -17,10 +17,10 @@ export interface CommandTarget {
 }
 export declare function commandTarget(line: LineDef, machineId: string): CommandTarget;
 /** The row that asks a machine for `op`: pass it to conditional(), or create it through the API. */
-export declare function commandRow(target: CommandTarget, op: Op, args?: Record<string, unknown>): {
+export declare function commandRow(target: CommandTarget, op: string, args?: Record<string, unknown>): {
     role: string;
     type: "machine-command";
-    subtype: Op;
+    subtype: string;
     description: string;
     priority: number;
     metadata: Record<string, unknown>;

package/build/services/machines/commands.js

@@ -1,8 +1,9 @@
 "use strict";
 /**
  * Commands as rows. A host asks a machine to start, stop, pause, resume,
- * change over or cancel a job by parking a machine-command row on the machine's role, from a
- * workflow step or through the API, the same way it asks a person for
+ * change over, cancel a job, report a snapshot, or do anything its codec
+ * declares (`rowOps`), by parking a machine-command row on the machine's role,
+ * from a workflow step or through the API, the same way it asks a person for
  * anything. The gateway sends the command and resolves the row with the
  * machine's reply (CommandResolution), so the step reads the outcome as data.
  */

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

@@ -29,7 +29,6 @@ export interface MachineLineConfig {
     mqtt?: MqttEndpoint;
     replyTimeoutMs: number;
     dispatchAttempts: number;
-    handoffTimeout: string;
     offlineDebounceMs: number;
     /** A connected machine silent this long gets a quiet row; 0 turns the check off. */
     quietMs: number;
@@ -41,6 +40,10 @@ export interface MachineLineConfig {
     lifecycle: boolean;
     /** With lifecycle notes, progress is noted each time it crosses this many percent; 0 notes none. */
     progressStep: number;
+    /** Telemetry messages are published as wire events too; off by default, since they are read live and many. */
+    wireTelemetry: boolean;
+    /** How many of the line's last wire events the leader keeps for GET .../wire. */
+    wireWindow: number;
     ltBaseUrl: string;
 }
 type Env = Record<string, string | undefined>;

package/build/services/machines/config.js

@@ -68,13 +68,14 @@ function loadMachineLineConfig(env = process.env) {
         lineConfigPath: env.MACHINE_LINE_CONFIG || undefined,
         replyTimeoutMs: int(env, 'MACHINE_REPLY_TIMEOUT_MS', protocol_1.REPLY_DEADLINE_MS),
         dispatchAttempts: Math.max(1, int(env, 'MACHINE_DISPATCH_ATTEMPTS', 3)),
-        handoffTimeout: env.MACHINE_HANDOFF_TIMEOUT ?? '10m',
         offlineDebounceMs: int(env, 'MACHINE_OFFLINE_DEBOUNCE_MS', 15_000),
         quietMs: int(env, 'MACHINE_QUIET_MS', 90_000),
         dispatchTtlMs: int(env, 'MACHINE_DISPATCH_TTL_MS', 600_000),
         receiptDelayMs: int(env, 'MACHINE_RECEIPT_DELAY_MS', 250),
         lifecycle: oneOf('MACHINE_LIFECYCLE', env.MACHINE_LIFECYCLE || SWITCH.OFF, Object.values(SWITCH)) === SWITCH.ON,
         progressStep: percentStep(env, 'MACHINE_PROGRESS_STEP', 25),
+        wireTelemetry: oneOf('MACHINE_WIRE_TELEMETRY', env.MACHINE_WIRE_TELEMETRY || SWITCH.OFF, Object.values(SWITCH)) === SWITCH.ON,
+        wireWindow: Math.max(1, int(env, 'MACHINE_WIRE_WINDOW', 500)),
         ltBaseUrl: env.LT_BASE_URL ?? 'http://localhost:3000',
     };
     if (transport === exports.MACHINE_TRANSPORT.NATS) {

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

@@ -16,12 +16,16 @@ export declare const ROW_TYPE: {
     readonly CONTRACT_VIOLATION: "contract-violation";
     /** An address claims a station the line already knows by another address, or the reverse: a person approves or rejects. */
     readonly MACHINE_REGISTRATION: "machine-registration";
+    /** Units a machine finished on hold wait for a quality decision: release, rework or scrap. */
+    readonly QUALITY_HOLD: "quality-hold";
 };
 export declare const LINE_ROLE: {
     /** People who clear alarms, bring machines back and decide failed handoffs. */
     readonly OPERATOR: "line-operator";
     /** People who take finished units off the line: the final handoff. */
     readonly EXIT: "line-exit";
+    /** People who decide units a machine finished on hold. */
+    readonly QUALITY: "line-quality";
     /** The gateway's own identity. */
     readonly CONTROLLER: "line-controller";
 };
@@ -43,6 +47,8 @@ export interface HandoffUnit {
     artifacts?: ArtifactRef[];
     /** Parameters for this unit alone, sent to the machine as given. */
     parameters?: Record<string, unknown>;
+    /** The host's references for this unit, by name; sent to the machine as given and searchable on the row. */
+    refs?: Record<string, string>;
 }
 /** Metadata on a handoff row. Everything a dispatch needs rides here. */
 export interface HandoffFacets {
@@ -66,6 +72,8 @@ export interface HandoffFacets {
     attempt: number;
     /** Parameters for the job, sent to the machine as given; what they mean is between the host and its codec. */
     parameters?: Record<string, unknown>;
+    /** The host's references for the job, by name (an order, a batch, a ticket); sent to the machine as given and searchable on the row. */
+    refs?: Record<string, string>;
 }
 /**
  * Items a handoff row accumulates, one per unit: the sender's finished-job
@@ -112,6 +120,8 @@ export declare const HANDOFF_ERROR: {
     readonly SOFTWARE_UNSUPPORTED: "software-unsupported";
     readonly WITHDRAWN: "withdrawn";
     readonly CANCELLED: "cancelled";
+    /** An arrival no open handoff into the machine expects, shown to the operator role once per machine and carrier. */
+    readonly UNMATCHED_ARRIVAL: "unmatched-arrival";
 };
 export type HandoffErrorCode = typeof HANDOFF_ERROR[keyof typeof HANDOFF_ERROR];
 /** A material lot a machine consumed for a unit. */
@@ -151,8 +161,12 @@ export interface HandoffResolution {
     /** The machine that reported the error, when it is not the one resolving. */
     reportedBy?: string;
     errorCode?: HandoffErrorCode;
+    /** On `sender-rejected`, how the sender finished the unit: reject, hold, scrap or rework. */
+    result?: string;
     reason?: string | null;
     detail?: string;
+    /** The machine's structured code for a refusal or failure, when its reply carried one. */
+    code?: string;
 }
 /** Decisions on line-operator rows: failed handoffs, alarms, dark machines, contested registrations. */
 export declare const DECISION: {
@@ -164,6 +178,10 @@ export declare const DECISION: {
     readonly RESTORED: "restored";
     readonly APPROVE: "approve";
     readonly REJECT: "reject";
+    /** A quality decision on held units: they continue from where they are. */
+    readonly RELEASE: "release";
+    /** A quality decision on held units: they run again from a station on the route. */
+    readonly REWORK: "rework";
 };
 export type Decision = typeof DECISION[keyof typeof DECISION];
 /** The decisions an operator may take on a failed handoff; retry only while every unit is still at the sender. */
@@ -172,11 +190,19 @@ export interface OperatorResolution {
     decision: Decision;
     note?: string;
 }
+/** The decisions a quality role may take on units a machine finished on hold. */
+export declare const HOLD_DECISIONS: readonly Decision[];
+export interface QualityResolution extends OperatorResolution {
+    /** For `rework`: the station the units run again from; the holding station when absent. */
+    station?: string;
+}
 /** Signal keys for the unit workflow; every attempt mints a fresh key. */
 export declare const signalKeys: {
     handoff: (jobKey: string, step: number, attempt: number) => string;
     handoffError: (jobKey: string, step: number, attempt: number, round?: number) => string;
     jobStop: (jobKey: string, step: number, attempt: number) => string;
+    hold: (jobKey: string, step: number, attempt: number, round?: number) => string;
+    disposition: (jobKey: string, step: number, attempt: number) => string;
 };
 /** Metadata on a machine-command row. */
 export interface CommandFacets {
@@ -202,6 +228,8 @@ export interface CommandResolution {
     op: string;
     status: CommandStatus;
     reason?: string;
+    /** The machine's structured code for the outcome, when its reply carried one. */
+    code?: string;
 }
 /** A row's dispatch command in its validity round; a later round is a new command (gateway/pacing.ts dispatchWindow). */
 export declare const dispatchCommandId: (escalationId: string, round?: number) => string;

package/build/services/machines/contracts.js

@@ -6,7 +6,7 @@
  * protocol that resolves it differs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cancelCommandId = exports.controlCommandId = exports.dispatchCommandId = exports.COMMAND_STATUS = exports.signalKeys = exports.DECISION = exports.LIFECYCLE_FACET = exports.TRACE_FACET = exports.HANDOFF_ERROR = exports.itemKeys = exports.LINE_ROLE = exports.ROW_TYPE = void 0;
+exports.cancelCommandId = exports.controlCommandId = exports.dispatchCommandId = exports.COMMAND_STATUS = exports.signalKeys = exports.HOLD_DECISIONS = exports.DECISION = exports.LIFECYCLE_FACET = exports.TRACE_FACET = exports.HANDOFF_ERROR = exports.itemKeys = exports.LINE_ROLE = exports.ROW_TYPE = void 0;
 exports.arrivedUnit = arrivedUnit;
 exports.handoffProgress = handoffProgress;
 exports.handoffDecisions = handoffDecisions;
@@ -24,12 +24,16 @@ exports.ROW_TYPE = {
     CONTRACT_VIOLATION: 'contract-violation',
     /** An address claims a station the line already knows by another address, or the reverse: a person approves or rejects. */
     MACHINE_REGISTRATION: 'machine-registration',
+    /** Units a machine finished on hold wait for a quality decision: release, rework or scrap. */
+    QUALITY_HOLD: 'quality-hold',
 };
 exports.LINE_ROLE = {
     /** People who clear alarms, bring machines back and decide failed handoffs. */
     OPERATOR: line_1.DEFAULT_OPERATOR_ROLE,
     /** People who take finished units off the line: the final handoff. */
     EXIT: line_1.DEFAULT_EXIT_ROLE,
+    /** People who decide units a machine finished on hold. */
+    QUALITY: line_1.DEFAULT_QUALITY_ROLE,
     /** The gateway's own identity. */
     CONTROLLER: 'line-controller',
 };
@@ -75,6 +79,8 @@ exports.HANDOFF_ERROR = {
     SOFTWARE_UNSUPPORTED: 'software-unsupported',
     WITHDRAWN: 'withdrawn',
     CANCELLED: 'cancelled',
+    /** An arrival no open handoff into the machine expects, shown to the operator role once per machine and carrier. */
+    UNMATCHED_ARRIVAL: 'unmatched-arrival',
     ...protocol_1.TRANSFER_FAILURE,
 };
 /**
@@ -95,6 +101,10 @@ exports.DECISION = {
     RESTORED: 'restored',
     APPROVE: 'approve',
     REJECT: 'reject',
+    /** A quality decision on held units: they continue from where they are. */
+    RELEASE: 'release',
+    /** A quality decision on held units: they run again from a station on the route. */
+    REWORK: 'rework',
 };
 /**
  * Failures a retry cannot repair. Units a sender finished as not ok leave the
@@ -107,11 +117,15 @@ function handoffDecisions(errorCode) {
     const noRetry = !!errorCode && NO_RETRY.includes(errorCode);
     return noRetry ? [exports.DECISION.MANUAL, exports.DECISION.SCRAP] : [exports.DECISION.RETRY, exports.DECISION.MANUAL, exports.DECISION.SCRAP];
 }
+/** The decisions a quality role may take on units a machine finished on hold. */
+exports.HOLD_DECISIONS = [exports.DECISION.RELEASE, exports.DECISION.REWORK, exports.DECISION.SCRAP];
 /** Signal keys for the unit workflow; every attempt mints a fresh key. */
 exports.signalKeys = {
     handoff: (jobKey, step, attempt) => `handoff-${jobKey}-s${step}-a${attempt}`,
     handoffError: (jobKey, step, attempt, round = 1) => `handoff-error-${jobKey}-s${step}-a${attempt}${round > 1 ? `-r${round}` : ''}`,
     jobStop: (jobKey, step, attempt) => `job-stop-${jobKey}-s${step}-a${attempt}`,
+    hold: (jobKey, step, attempt, round = 1) => `hold-${jobKey}-s${step}-a${attempt}${round > 1 ? `-r${round}` : ''}`,
+    disposition: (jobKey, step, attempt) => `disposition-${jobKey}-s${step}-a${attempt}`,
 };
 exports.COMMAND_STATUS = { ...protocol_1.REPLY_STATUS, NO_REPLY: 'no-reply', UNSUPPORTED: 'unsupported' };
 /** A row's dispatch command in its validity round; a later round is a new command (gateway/pacing.ts dispatchWindow). */

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

@@ -36,7 +36,7 @@ export declare const OPERATOR_FORM_SCHEMA: {
     properties: {
         decision: {
             type: string;
-            enum: ("reject" | "scrap" | "retry" | "manual" | "acknowledge" | "cleared" | "restored" | "approve")[];
+            enum: ("release" | "reject" | "scrap" | "rework" | "retry" | "manual" | "acknowledge" | "cleared" | "restored" | "approve")[];
             default: "acknowledge";
             description: string;
         };
@@ -53,3 +53,28 @@ export declare const OPERATOR_FORM_SCHEMA: {
         };
     };
 };
+export declare const QUALITY_FORM_SCHEMA: {
+    title: string;
+    description: string;
+    'x-lt-order': string[];
+    required: string[];
+    properties: {
+        decision: {
+            type: string;
+            enum: ("release" | "scrap" | "rework")[];
+            default: "release";
+            description: string;
+        };
+        station: {
+            type: string;
+            default: string;
+            description: string;
+        };
+        note: {
+            type: string;
+            format: string;
+            default: string;
+            description: string;
+        };
+    };
+};

package/build/services/machines/forms.js

@@ -6,7 +6,7 @@
  * handoffs and close alarm and machine-state rows.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPERATOR_FORM_SCHEMA = exports.HANDOFF_FORM_SCHEMA = void 0;
+exports.QUALITY_FORM_SCHEMA = exports.OPERATOR_FORM_SCHEMA = exports.HANDOFF_FORM_SCHEMA = void 0;
 const contracts_1 = require("./contracts");
 exports.HANDOFF_FORM_SCHEMA = {
     title: 'Receive units',
@@ -35,3 +35,19 @@ exports.OPERATOR_FORM_SCHEMA = {
         clearedBy: { type: 'string', default: '', description: 'Who cleared it at the machine, when the machine reports it' },
     },
 };
+exports.QUALITY_FORM_SCHEMA = {
+    title: 'Quality decision',
+    description: 'Units a machine finished on hold: release them to continue, send them back to a station for rework, or scrap them.',
+    'x-lt-order': ['decision', 'station', 'note'],
+    required: ['decision'],
+    properties: {
+        decision: {
+            type: 'string',
+            enum: [contracts_1.DECISION.RELEASE, contracts_1.DECISION.REWORK, contracts_1.DECISION.SCRAP],
+            default: contracts_1.DECISION.RELEASE,
+            description: 'Release, rework or scrap',
+        },
+        station: { type: 'string', default: '', description: 'For rework: the station the units run again from; the holding station when empty' },
+        note: { type: 'string', format: 'textarea', default: '', description: 'What was found' },
+    },
+};

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

@@ -18,14 +18,19 @@ export interface CreateRowInput {
     escalation_payload?: string;
 }
 export type Action = 
-/** `receivedOnAccept`: the units are already at the machine, so its acceptance completes the handoff. */
+/**
+ * `receivedOnAccept`: the units are already at the machine, so its acceptance completes the handoff.
+ * `ended`: the row already resolved; the job is sent again for units the machine still holds, and no verb touches the row.
+ */
 {
     kind: 'dispatch';
     rowId: string;
     machineId: string;
     cmdId: string;
     args: Record<string, any>;
+    issuedAt?: number;
     receivedOnAccept?: boolean;
+    ended?: boolean;
 } | {
     kind: 'command';
     machineId: string;
@@ -78,6 +83,8 @@ export type Action =
     cmdId: string;
     status: string;
     reason: string;
+    code?: string;
+    preparing?: boolean;
 }
 /** A machine reported the jobs it holds: answers a status query in flight. */
  | {
@@ -98,6 +105,12 @@ export type Action =
     machineId: string;
     address: string;
     reason: string;
+}
+/** Jobs a restarted machine lost that this gateway cannot send again: nothing of them is remembered. */
+ | {
+    kind: 'unrecoverable';
+    machineId: string;
+    jobs: string[];
 };
 /** Once the row holds every one of `keys`: resolve it with `payload`, or run `then` instead. */
 export interface Completion {

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

@@ -4,32 +4,58 @@
  * and under a strict codec a message that breaks the contract is held for a
  * person instead of acted on.
  */
+import type { OpenRowQuery } from '../rows';
 import { type LineDef } from '../../../lib/machines/line';
-import type { Inspection } from '../../../lib/machines/protocol';
+import { type Inspection } from '../../../lib/machines/protocol';
 import { type Disposition, type InboundMessage } from '../../../lib/machines/transport';
+import type { WireAction } from '../../../types/machines-view';
 import type { Action } from './actions';
 import { type GatewayLog } from './log';
 import type { GatewayState } from './state';
-/** What handling one decoded message came to. */
+/** What handling one decoded message came to, with what the gateway did for the wire record. */
 export interface Applied {
     disposition: Disposition;
     failed: boolean;
+    actions: WireAction[];
+    /** The address the message came from, when it was not admitted as a station's. */
+    sender?: {
+        machineId: string | null;
+        address: string | null;
+    };
+}
+/** A message admitted as a station's, with what admitting it did (a binding, say). */
+export interface Admitted {
+    seen: Inspection;
+    actions: WireAction[];
 }
 export interface AdmissionContext {
     state: GatewayState;
     line: LineDef;
     executor: {
-        apply(actions: Action[]): Promise<void>;
+        apply(actions: Action[]): Promise<WireAction[]>;
     };
     log: GatewayLog;
     /** Send waiting handoffs that may now go out. */
     pace(): Promise<void>;
+    /** The controller's pending rows of a type, for the rows shown to people once. */
+    openRows(query: OpenRowQuery): Promise<Record<string, any>[]>;
 }
 /**
  * The station a message is from (registration.ts). A newly claimed station is
  * bound and its waiting work goes out; a contested claim raises one row for a
  * person; either of those, and an address no station claims, is not acted on.
  */
-export declare function admitSender(ctx: AdmissionContext, topic: string, raw: Inspection): Promise<Inspection | Applied>;
+export declare function admitSender(ctx: AdmissionContext, topic: string, raw: Inspection): Promise<Admitted | Applied>;
 /** Under a strict codec a broken message is not acted on: a person sees it on a row, once. */
 export declare function holdViolation(ctx: AdmissionContext, msg: InboundMessage, seen: Inspection): Promise<Applied>;
+/** A job arrival: a scan, or a transfer that failed on the carrier read. */
+export declare function isArrival(seen: Inspection): boolean;
+/** An arrival that read no id at all: no row can ever claim it, so it goes to a person on its first delivery. */
+export declare function isUnreadableArrival(seen: Inspection): boolean;
+/**
+ * An arrival no open handoff into the machine expects, after every delivery:
+ * a person sees it on one handoff-error row per machine and carrier, with the
+ * raw arrival, so the unit can be re-scanned or routed. Resolving the row lets
+ * the next such arrival raise one again.
+ */
+export declare function holdArrival(ctx: AdmissionContext, msg: InboundMessage, seen: Inspection): Promise<Applied>;

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

@@ -8,11 +8,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.admitSender = admitSender;
 exports.holdViolation = holdViolation;
+exports.isArrival = isArrival;
+exports.isUnreadableArrival = isUnreadableArrival;
+exports.holdArrival = holdArrival;
 const contracts_1 = require("../contracts");
 const line_1 = require("../../../lib/machines/line");
+const protocol_1 = require("../../../lib/machines/protocol");
 const transport_1 = require("../../../lib/machines/transport");
+const dispatcher_1 = require("./dispatcher");
 const log_1 = require("./log");
 const registration_1 = require("./registration");
+function from(sender) {
+    return { machineId: sender.machineId ?? null, address: sender.address };
+}
 /**
  * The station a message is from (registration.ts). A newly claimed station is
  * bound and its waiting work goes out; a contested claim raises one row for a
@@ -20,47 +28,101 @@ const registration_1 = require("./registration");
  */
 async function admitSender(ctx, topic, raw) {
     const sender = (0, registration_1.resolveSender)(ctx.state, ctx.line, raw);
+    const actions = [];
     try {
         if (sender.status === registration_1.SENDER.BOUND) {
-            await ctx.executor.apply([{ kind: 'bindAddress', machineId: sender.machineId, address: sender.address }]);
+            actions.push(...await ctx.executor.apply([{ kind: 'bindAddress', machineId: sender.machineId, address: sender.address }]));
             await ctx.pace();
         }
         if (sender.seen)
-            return sender.seen;
+            return { seen: sender.seen, actions };
         if (sender.status === registration_1.SENDER.CONTESTED)
             ctx.state.hearClaim(sender.address, sender.machineId);
         if (sender.status === registration_1.SENDER.CONTESTED && !ctx.state.claimRaised(sender.address, sender.machineId)) {
-            await ctx.executor.apply([{ kind: 'createRow', row: (0, registration_1.registrationRow)(ctx.state, ctx.line, sender.address, sender.machineId) }]);
-            ctx.state.raiseClaim(sender.address, sender.machineId);
+            const [made] = await ctx.executor.apply([{ kind: 'createRow', row: (0, registration_1.registrationRow)(ctx.state, ctx.line, sender.address, sender.machineId) }]);
+            ctx.state.raiseClaim(sender.address, sender.machineId, made?.rowId);
             ctx.log.warn(log_1.GATEWAY_LOG.ADDRESS_CONTESTED, { topic, address: sender.address, machine: sender.machineId });
+            actions.push({ ...made, detail: `${sender.address} says it is ${sender.machineId}; a person decides` });
+        }
+        else if (sender.status === registration_1.SENDER.CONTESTED) {
+            actions.push({ verb: 'none', detail: `${sender.address} says it is ${sender.machineId}; waiting for a person` });
         }
-        if (sender.status === registration_1.SENDER.UNKNOWN && ctx.state.firstHeardStranger(sender.address))
-            ctx.log.warn(log_1.GATEWAY_LOG.ADDRESS_UNKNOWN, { topic, address: sender.address });
-        return { disposition: transport_1.DISPOSITION.ACK, failed: false };
+        if (sender.status === registration_1.SENDER.UNKNOWN) {
+            if (ctx.state.firstHeardStranger(sender.address))
+                ctx.log.warn(log_1.GATEWAY_LOG.ADDRESS_UNKNOWN, { topic, address: sender.address });
+            actions.push({ verb: 'none', detail: `${sender.address} claims no station on this line` });
+        }
+        return { disposition: transport_1.DISPOSITION.ACK, failed: false, actions, sender: from(sender) };
     }
     catch (err) {
-        ctx.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic, error: err.message });
-        return { disposition: transport_1.DISPOSITION.NAK, failed: true };
+        if (!(err instanceof dispatcher_1.GatewayStopped))
+            ctx.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic, error: err.message });
+        return { disposition: transport_1.DISPOSITION.NAK, failed: true, actions, sender: from(sender) };
     }
 }
 /** Under a strict codec a broken message is not acted on: a person sees it on a row, once. */
 async function holdViolation(ctx, msg, seen) {
     const { ident, kind } = seen.parsed;
     const key = seen.receiptId ?? seen.body?.id ?? `${msg.topic}:${msg.payload}`;
+    const detail = seen.violations.join('; ');
     if (ctx.state.violationRaised(key))
-        return { disposition: transport_1.DISPOSITION.ACK, failed: false };
+        return { disposition: transport_1.DISPOSITION.ACK, failed: false, actions: [{ verb: 'hold', detail: `${detail} (already shown to a person)` }] };
     try {
-        await ctx.executor.apply([{ kind: 'createRow', row: {
+        const [made] = await ctx.executor.apply([{ kind: 'createRow', row: {
                     type: contracts_1.ROW_TYPE.CONTRACT_VIOLATION, role: (0, line_1.operatorRole)(ctx.line), priority: 2,
                     description: `${ident.machineId} sent a ${kind} message that breaks the contract: ${seen.violations.join('; ')}`,
                     metadata: { siteId: ident.siteId, lineId: ident.lineId, machineId: ident.machineId, kind, topic: msg.topic, messageId: seen.body?.id ?? null, violations: seen.violations },
                     escalation_payload: msg.payload,
                 } }]);
         ctx.state.raiseViolation(key);
-        return { disposition: transport_1.DISPOSITION.ACK, failed: false };
+        return { disposition: transport_1.DISPOSITION.ACK, failed: false, actions: [{ verb: 'hold', rowId: made?.rowId, detail }] };
+    }
+    catch (err) {
+        if (!(err instanceof dispatcher_1.GatewayStopped))
+            ctx.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic: msg.topic, error: err.message });
+        return { disposition: transport_1.DISPOSITION.NAK, failed: true, actions: [] };
+    }
+}
+/** A job arrival: a scan, or a transfer that failed on the carrier read. */
+function isArrival(seen) {
+    const event = seen.body?.body?.event;
+    return seen.parsed?.kind === protocol_1.MESSAGE_KIND.JOB && (event === protocol_1.JOB_EVENT.ARRIVED || event === protocol_1.JOB_EVENT.TRANSFER_FAILED);
+}
+/** An arrival that read no id at all: no row can ever claim it, so it goes to a person on its first delivery. */
+function isUnreadableArrival(seen) {
+    return seen.parsed?.kind === protocol_1.MESSAGE_KIND.JOB && (0, protocol_1.isUnreadableRead)(seen.body?.body ?? {});
+}
+/**
+ * An arrival no open handoff into the machine expects, after every delivery:
+ * a person sees it on one handoff-error row per machine and carrier, with the
+ * raw arrival, so the unit can be re-scanned or routed. Resolving the row lets
+ * the next such arrival raise one again.
+ */
+async function holdArrival(ctx, msg, seen) {
+    const { ident } = seen.parsed;
+    const body = seen.body?.body ?? {};
+    const carrierId = typeof body.carrierId === 'string' ? body.carrierId : null;
+    const unitId = typeof body.unitId === 'string' ? body.unitId : null;
+    const detail = `no handoff into ${ident.machineId} expects ${carrierId ? `carrier ${carrierId}` : 'an unreadable carrier'}`;
+    try {
+        const open = await ctx.openRows({ type: contracts_1.ROW_TYPE.HANDOFF_ERROR, role: (0, line_1.operatorRole)(ctx.line) });
+        const shown = open.find((r) => r.metadata?.errorCode === contracts_1.HANDOFF_ERROR.UNMATCHED_ARRIVAL && r.metadata?.machineId === ident.machineId && (r.metadata?.carrierId ?? null) === carrierId);
+        if (shown)
+            return { disposition: transport_1.DISPOSITION.ACK, failed: false, actions: [{ verb: 'unmatched', rowId: shown.id, detail: `${detail} (already shown to a person)` }] };
+        const [made] = await ctx.executor.apply([{ kind: 'createRow', row: {
+                    type: contracts_1.ROW_TYPE.HANDOFF_ERROR, role: (0, line_1.operatorRole)(ctx.line), priority: 2,
+                    description: `${ident.machineId} reports an arrival no handoff expects: ${carrierId ? `carrier ${carrierId}` : 'the carrier could not be read'}`,
+                    metadata: {
+                        siteId: ident.siteId, lineId: ident.lineId, machineId: ident.machineId, errorCode: contracts_1.HANDOFF_ERROR.UNMATCHED_ARRIVAL,
+                        carrierId, unitId, event: body.event, topic: msg.topic, messageId: seen.body?.id ?? null, arrival: body,
+                    },
+                    escalation_payload: msg.payload,
+                } }]);
+        return { disposition: transport_1.DISPOSITION.ACK, failed: false, actions: [{ verb: 'create-row', rowId: made?.rowId, detail }] };
     }
     catch (err) {
-        ctx.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic: msg.topic, error: err.message });
-        return { disposition: transport_1.DISPOSITION.NAK, failed: true };
+        if (!(err instanceof dispatcher_1.GatewayStopped))
+            ctx.log.error(log_1.GATEWAY_LOG.VERB_FAILED, { topic: msg.topic, error: err.message });
+        return { disposition: transport_1.DISPOSITION.NAK, failed: true, actions: [] };
     }
 }

package/build/services/machines/gateway/api-escalations.js

@@ -42,6 +42,8 @@ const escalationApi = __importStar(require("../../../api/escalations"));
 const uuid_1 = require("../../../lib/uuid");
 const escalations_1 = require("./escalations");
 const actions_1 = require("./actions");
+/** A row that was never given items (one parked by hand) answers 400; it holds none. */
+const NO_ITEMS_STATUS = 400;
 class ApiLineEscalations {
     constructor(userFor) {
         this.userFor = userFor;
@@ -75,6 +77,8 @@ class ApiLineEscalations {
     }
     async items(id) {
         const result = await escalationApi.getEscalationItems({ id }, this.auth(actions_1.CONTROLLER));
+        if (result.status === NO_ITEMS_STATUS)
+            return [];
         if (result.status >= 300)
             throw new Error(`items failed ${result.status}: ${result.error}`);
         return result.data.items.map((i) => ({ itemKey: i.itemKey, payload: i.payload ?? {} }));